chore(api-ref): Uplift API reference docs: #5595
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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.
…er strings in tags ('/' for legacy paths).
… 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.
…CDN with package from npm and js.Build
- 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
force-pushed
the
api-uplift
branch
from
deeb945 to
a5e6380
Compare
17 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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, runChanges as of 11/5:
Changes as of 9/23:
/dataor separate files--only pages.typeproperty for API reference (OpenAPI) paths. For example, if the page structure iscontent/influxdb/v2/api/v2/[OpenAPI path], then addtype: api_pathto the frontmatter and, if necessary, specify a layout:layout: api_path.