docs-v2/api-docs/README.md

How to generate InfluxDB API docs

InfluxData uses Redoc, redoc-cli, and Redocly's OpenApi CLI to generate API documentation from the InfluxDB OpenAPI (aka Swagger) contracts.

To minimize the size of the docs-v2 repository, the generated API documentation HTML is gitignored, therefore not committed to the docs repo. The InfluxDB docs deployment process uses OpenAPI specification files in the api-docs directory to generate version-specific (Cloud, OSS v2.1, OSS v2.0, etc.) API documentation.

How we version OpenAPI contracts

The api-docs directory structure versions OpenAPI files using the following pattern:

api-docs/
  ├── v2.0/
  │     └── ref.yml
  │     └── swaggerV1Compat.yml
  ├── v2.1/
  │     └── ref.yml
  │     └── swaggerV1Compat.yml
  ├── v2.2/
  │     └── ref.yml
  │     └── swaggerV1Compat.yml
  └── etc...

InfluxDB Cloud version

Because InfluxDB Cloud releases are frequent, we make no effort to version the Cloud API spec. We regenerate API reference docs from influxdata/openapi master as features are released.

InfluxDB OSS version

Given that influxdata/openapi master may contain OSS spec changes not implemented in the current OSS release, we (Docs team) maintain a release branch, influxdata/openapi docs-release/influxdb-oss, used to generate OSS reference docs.

To update this branch to a new OSS release, (re)base on the commit or tag for the latest release of InfluxDB OSS.

git checkout docs-release/influxdb-oss
git rebase -i influxdb-oss-v2.2.0
git push -f origin docs-release/influxdb-oss

To update this branch with documentation changes between OSS releases, cherry-pick your documentation commits into the release branch.

git checkout docs-release/influxdb-oss
git cherry-pick <commit hashes>
git push -f origin docs-release/influxdb-oss

How to find the API spec used by an InfluxDB OSS version

influxdata/openapi does not version the InfluxData API. To find the influxdata/openapi commit SHA used in a specific version of InfluxDB OSS, see /scripts/fetch-swagger.sh in influxdata/influxdb--for example, for the influxdata/openapi commit used in OSS v2.2.0, see https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=. For convenience, we tag influxdata/influxdb (OSS) release points in influxdata/openapi as influxdb-oss-v[OSS_VERSION]. See https://github.com/influxdata/openapi/tags.

How to fetch and process influxdata/openapi contracts

Update the contracts in api-docs to the latest from influxdata/openapi.

# In your terminal, go to the `docs-v2/api-docs` directory:
cd api-docs

# Fetch the contracts and run @redocly/openapi-cli to customize and bundle them.
sh getswagger.sh oss; sh getswagger.sh cloud

How to generate API docs locally

Because the API documentation HTML is gitignored, you must manually generate it to view the API docs locally.

Verify that you have a working npx (it's included with Node.js). In your terminal, run:

npx --version

If npx returns errors, download and run a recent version of the Node.js installer for your OS.

# In your terminal, go to the `docs-v2/api-docs` directory:
cd api-docs

# Generate the API docs with Redocly
sh generate-api-docs.sh

How to use custom OpenAPI spec processing

Generally, you should manage API content in influxdata/openapi. In some cases, however, you may want custom processing (e.g. collecting all Tags) or additional content (e.g. describing the reference documentation) specifically for the docs.

When you run getswagger.sh, it executes @redocly/openapi-cli and the plugins listed in .redocly.yaml. ./openapi/plugins use ./openapi/plugins/decorators to apply custom processing to OpenAPI specs.

.yml files in ./openapi/content set content for sections (nodes) in the contract. To update the content for those nodes, you only need to update the YAML files. To add new YAML files for other nodes in the contracts, configure the new content YAML file in ./openapi/content/content.js. The content structure and Markdown must be valid OAS.

Then, you'll need to write or update a decorator module for the node and configure the decorator in the plugin, e.g. ./openapi/plugins/docs-plugin.js. See the complete list of OAS v3.0 nodes.

@redocly/openapi-cli requires that modules use CommonJS require syntax for imports.

How to add tag content or describe a group of paths

In API reference docs, we use OpenAPI tags elements for navigation and the x-traitTag vendor extension to define custom content.

Example	OpenAPI field
Add supplementary documentation	tags: [ { name: 'Quick start', x-traitTag: true } ]	Source
Group and describe related paths	tags: [ { name: 'Buckets', description: '...' } ]	Source)

How to test your spec or API reference changes

You can use getswagger.sh to fetch contracts from any URL. For example, if you've made changes to spec files and generated new contracts in your local openapi repo, run getswagger.sh to fetch and process them.

To fetch contracts from your own openapi repo, pass the -b base_url option and the full path to your openapi directory.

# Use the file:/// protocol to pass your openapi directory.
sh getswagger.sh oss -b file:///Users/me/github/openapi

After you fetch them, run the linter or generate HTML to test your changes before you commit them to influxdata/openapi. By default, getswagger.sh doesn't run the linter when bundling the specs. Manually run the linter rules to get a report of errors and warnings.

npx @redocly/openapi-cli lint v2.1/ref.yml

Configure OpenAPI CLI linting and bundling

The .redoc.yaml configuration file sets options for the @redocly/openapi-cli lint and bundle commands. ./openapi/plugins contains custom InfluxData Docs plugins composed of rules (for validating and linting) and decorators (for customizing). For more configuration options, see @redocly/openapi-cli configuration file documentation.