Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(api-ref): Uplift API reference docs: #5595

Draft
wants to merge 14 commits into
base: master
Choose a base branch
from
Draft

chore(api-ref): Uplift API reference docs: #5595

wants to merge 14 commits into from

Commits on Nov 5, 2024

  1. chore(api-ref): Uplift API reference docs: 

    - Adapts code from @jstirnaman's demo site to generate Hugo pages from OpenAPI paths in the InfluxDB spec files.
- Uses Rapidoc to render the OpenAPI path in a page--effectively treating each endpoint as a standalone API for faster loading.
- Run yarn install and then Executing: api-docs/getswagger.sh cloud-v2 -B
No URL was provided. I'll rebuild from the existing spec /Users/ja/Documents/github/docs-v2/api-docs/cloud/v2/ref.yml
10.8.2
Generating OpenAPI path files in static/openapi/influxdb-cloud-v2/paths....
Generating OpenAPI article data in data/article-data/influxdb/cloud-v2...
Executing: HUGO_DATAPAGES_DATA_PATH=data/article-data/influxdb/cloud-v2     HUGO_DATAPAGES_ELEMENT=articles     HUGO_DATAPAGES_TYPE=api     HUGO_DATAPAGES_CONTENT_PATH=content/influxdb/cloud/api/v2     node hugo-data-to-pages/hugo.js clean --force
Removing data-generated files...
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-authorizations
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-buckets
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-checks
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-dashboards
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-dbrps
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-delete
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-flags
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-labels
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-maps
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-me
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-notificationEndpoints
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-notificationRules
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-orgs
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-query
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-resources
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-scripts
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-setup
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-signin
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-signout
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-stacks
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-tasks
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-telegraf
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-telegrafs
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-templates
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-users
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-variables
Removed folder: ./content/influxdb/cloud/api/v2/api-v2-write
Removed folder: ./content/influxdb/cloud/api/v2/api-v2
Removed folder: ./content/influxdb/cloud/api/v2/legacy-authorizations
Removed folder: ./content/influxdb/cloud/api/v2/ping
Removed folder: ./content/influxdb/cloud/api/v2/query
Removed folder: ./content/influxdb/cloud/api/v2/write
Done!
Executing: HUGO_DATAPAGES_DATA_PATH=data/article-data/influxdb/cloud-v2     HUGO_DATAPAGES_ELEMENT=articles     HUGO_DATAPAGES_TYPE=api     HUGO_DATAPAGES_CONTENT_PATH=content/influxdb/cloud/api/v2     node hugo-data-to-pages/hugo.js generate
Building data-generated files...
Created file: ./content/influxdb/cloud/api/v2/api-v2-authorizations/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-buckets/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-checks/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-dashboards/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-dbrps/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-delete/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-flags/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-labels/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-maps/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-me/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-notificationEndpoints/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-notificationRules/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-orgs/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-query/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-resources/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-scripts/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-setup/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-signin/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-signout/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-stacks/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-tasks/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-telegraf/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-telegrafs/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-templates/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-users/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-variables/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2-write/index.md
Created file: ./content/influxdb/cloud/api/v2/api-v2/index.md
Created file: ./content/influxdb/cloud/api/v2/legacy-authorizations/index.md
Created file: ./content/influxdb/cloud/api/v2/ping/index.md
Created file: ./content/influxdb/cloud/api/v2/query/index.md
Created file: ./content/influxdb/cloud/api/v2/write/index.md
Done!
Executing: api-docs/getswagger.sh oss-v2 -B
No URL was provided. I'll rebuild from the existing spec /Users/ja/Documents/github/docs-v2/api-docs/v2/ref.yml
10.8.2
Generating OpenAPI path files in static/openapi/influxdb-oss-v2/paths....
Generating OpenAPI article data in data/article-data/influxdb/oss-v2...
Executing: HUGO_DATAPAGES_DATA_PATH=data/article-data/influxdb/oss-v2     HUGO_DATAPAGES_ELEMENT=articles     HUGO_DATAPAGES_TYPE=api     HUGO_DATAPAGES_CONTENT_PATH=content/influxdb/v2/api/v2     node hugo-data-to-pages/hugo.js clean --force
Removing data-generated files...
Removed folder: ./content/influxdb/v2/api/v2/api-v2-authorizations
Removed folder: ./content/influxdb/v2/api/v2/api-v2-backup
Removed folder: ./content/influxdb/v2/api/v2/api-v2-buckets
Removed folder: ./content/influxdb/v2/api/v2/api-v2-checks
Removed folder: ./content/influxdb/v2/api/v2/api-v2-config
Removed folder: ./content/influxdb/v2/api/v2/api-v2-dashboards
Removed folder: ./content/influxdb/v2/api/v2/api-v2-dbrps
Removed folder: ./content/influxdb/v2/api/v2/api-v2-delete
Removed folder: ./content/influxdb/v2/api/v2/api-v2-flags
Removed folder: ./content/influxdb/v2/api/v2/api-v2-labels
Removed folder: ./content/influxdb/v2/api/v2/api-v2-maps
Removed folder: ./content/influxdb/v2/api/v2/api-v2-me
Removed folder: ./content/influxdb/v2/api/v2/api-v2-notificationEndpoints
Removed folder: ./content/influxdb/v2/api/v2/api-v2-notificationRules
Removed folder: ./content/influxdb/v2/api/v2/api-v2-orgs
Removed folder: ./content/influxdb/v2/api/v2/api-v2-query
Removed folder: ./content/influxdb/v2/api/v2/api-v2-remotes
Removed folder: ./content/influxdb/v2/api/v2/api-v2-replications
Removed folder: ./content/influxdb/v2/api/v2/api-v2-resources
Removed folder: ./content/influxdb/v2/api/v2/api-v2-restore
Removed folder: ./content/influxdb/v2/api/v2/api-v2-scrapers
Removed folder: ./content/influxdb/v2/api/v2/api-v2-setup
Removed folder: ./content/influxdb/v2/api/v2/api-v2-signin
Removed folder: ./content/influxdb/v2/api/v2/api-v2-signout
Removed folder: ./content/influxdb/v2/api/v2/api-v2-sources
Removed folder: ./content/influxdb/v2/api/v2/api-v2-stacks
Removed folder: ./content/influxdb/v2/api/v2/api-v2-tasks
Removed folder: ./content/influxdb/v2/api/v2/api-v2-telegraf
Removed folder: ./content/influxdb/v2/api/v2/api-v2-telegrafs
Removed folder: ./content/influxdb/v2/api/v2/api-v2-templates
Removed folder: ./content/influxdb/v2/api/v2/api-v2-users
Removed folder: ./content/influxdb/v2/api/v2/api-v2-variables
Removed folder: ./content/influxdb/v2/api/v2/api-v2-write
Removed folder: ./content/influxdb/v2/api/v2/api-v2
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-all
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-allocs
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-block
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-cmdline
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-goroutine
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-heap
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-mutex
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-profile
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-threadcreate
Removed folder: ./content/influxdb/v2/api/v2/debug-pprof-trace
Removed folder: ./content/influxdb/v2/api/v2/health
Removed folder: ./content/influxdb/v2/api/v2/legacy-authorizations
Removed folder: ./content/influxdb/v2/api/v2/metrics
Removed folder: ./content/influxdb/v2/api/v2/ping
Removed folder: ./content/influxdb/v2/api/v2/query
Removed folder: ./content/influxdb/v2/api/v2/ready
Removed folder: ./content/influxdb/v2/api/v2/write
Done!
Executing: HUGO_DATAPAGES_DATA_PATH=data/article-data/influxdb/oss-v2     HUGO_DATAPAGES_ELEMENT=articles     HUGO_DATAPAGES_TYPE=api     HUGO_DATAPAGES_CONTENT_PATH=content/influxdb/v2/api/v2     node hugo-data-to-pages/hugo.js generate
Building data-generated files...
Created file: ./content/influxdb/v2/api/v2/api-v2-authorizations/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-backup/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-buckets/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-checks/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-config/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-dashboards/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-dbrps/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-delete/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-flags/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-labels/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-maps/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-me/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-notificationEndpoints/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-notificationRules/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-orgs/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-query/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-remotes/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-replications/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-resources/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-restore/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-scrapers/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-setup/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-signin/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-signout/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-sources/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-stacks/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-tasks/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-telegraf/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-telegrafs/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-templates/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-users/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-variables/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2-write/index.md
Created file: ./content/influxdb/v2/api/v2/api-v2/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-all/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-allocs/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-block/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-cmdline/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-goroutine/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-heap/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-mutex/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-profile/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-threadcreate/index.md
Created file: ./content/influxdb/v2/api/v2/debug-pprof-trace/index.md
Created file: ./content/influxdb/v2/api/v2/health/index.md
Created file: ./content/influxdb/v2/api/v2/legacy-authorizations/index.md
Created file: ./content/influxdb/v2/api/v2/metrics/index.md
Created file: ./content/influxdb/v2/api/v2/ping/index.md
Created file: ./content/influxdb/v2/api/v2/query/index.md
Created file: ./content/influxdb/v2/api/v2/ready/index.md
Created file: ./content/influxdb/v2/api/v2/write/index.md
Done! to generate the paths, metadata, and pages.
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    dd2b07c View commit details
    Browse the repository at this point in the history

  2. fix(api): Use forked hugo-data-to-pages. Add async. 

    - Replaces hugo-data-to-pages with forked repo that accepts a config object and uses a more recent version of js-yaml.
- Uses async to wait for scripts to complete.
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    fe603d6 View commit details
    Browse the repository at this point in the history

  3. Add configuration. Store output paths and metadata in /data. Refactor… 

    …s and simplifying module and function names.
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    83f3cf7 View commit details
    Browse the repository at this point in the history

  4. chore: Generalize.

    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    34dc8a6 View commit details
    Browse the repository at this point in the history

  5. fix: removes empty strings resulting from snakifying non-word charact… 

    …er strings in tags ('/' for legacy paths).
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    ecc56ab View commit details
    Browse the repository at this point in the history

  6. WIP: draft TODO. Simplify code.

    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    34e6d29 View commit details
    Browse the repository at this point in the history

  7. fix(api): update yarn.lock

    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    f368438 View commit details
    Browse the repository at this point in the history

  8. To build the API pages, run yarn run build-apidocs from the project… 

    … directory.

No longer uses Hugo /data.
Removes dependency on the Hugo-data-to-pages script.
For each product endpoint, generate a page with the endpoint spec inside the frontmatter.
Writes endpoint specs into each page's frontmatter.
Assign a `type` property for API reference (OpenAPI) paths. For example, if the page structure is `content/influxdb/v2/api/v2/[OpenAPI path]`, then add `type: api_path` to the frontmatter and, if necessary, specify a layout: `layout: api_path`.
Renders the spec param JSON using Rapidoc.

TODO:
- Cleanup
- Create additional templates that process page data for nav, filtering, links, code samples, etc.
- Fix circular reference issues in specs that prevent generating a dereferenced JSON bundle (which could also help us our own custom UI...should we choose).
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    bd31940 View commit details
    Browse the repository at this point in the history

  9. fix(oss): Update TLS example using openssl and including Subject Alte… 

    …rnative Name (SAN)

- Example uses Subject Alternative Name extension required by modern clients.
- Updated example is more verbose, but should work cross-platform.
- Added troubleshooting steps.
- Passes tests.
- Reformatted to headings and remove list nesting.
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    c8d083d View commit details
    Browse the repository at this point in the history

  10. chore(api): Use Spectral for linting OpenAPI

    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    fe49069 View commit details
    Browse the repository at this point in the history

  11. WIP(api): hide rapidoc sidebar, add API _index page, replace rapidoc … 

    …CDN with package from npm and js.Build
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    b2ef303 View commit details
    Browse the repository at this point in the history

  12. chore(api): Refactor and reuse data: 

    - Makes OSS v2 config consistent with other platforms and more convenient
- Changes getSwagger.sh to use the new v2 config and to allow generating v1-compat individually for each platform
- Refactors JS into modules.
- Reuses existing product (platform) data
- Adds an apis property to product data that references the config file for each product's API docs
- Generates pages for all products that have the  property
- Adds the script to package.json
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    5ad7bc4 View commit details
    Browse the repository at this point in the history

  13. WIP(api): JavaScript module refactor, API stylesheets and theme switc… 

    …hing

- Use js.Build in asset pipeline to transpile and tree-shake ESM modules
- Reorganize JS from HTML sections into modular ESM (benefts: testing, intellisense, package management, explicit dependencies (imports)
- Move some code into Reactish functional components
- Light/dark theme switching for Rapidoc
- Basic light/dark SCSS setup
- Inherits the user's preferred server URL and sets it as the API server URL
    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    a5e6380 View commit details
    Browse the repository at this point in the history

  14. WIP(api): Fix background color, remove unused style attributes.

    @jstirnaman
    jstirnaman committed Nov 5, 2024
    Configuration menu
    Copy the full SHA
    4e3dd62 View commit details
    Browse the repository at this point in the history