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.

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

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

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

Conversation

jstirnaman
Copy link
Contributor

@jstirnaman jstirnaman commented Sep 6, 2024

⚠️ For demo only - Don't merge!

  • 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.
    To build the API pages, inside DOCS_ROOT, run

    yarn run build-apidocs

Changes as of 11/5:

  • 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
image image

Changes as of 9/23:

  • No longer uses Hugo /data or separate files--only pages.
  • 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.

- 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.
- 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.
…s and simplifying module and function names.
… 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).
…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.
- 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
…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 linked an issue Nov 5, 2024 that may be closed by this pull request
17 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

API reference uplift
1 participant