Skip to content

Latest commit

 

History

History
41 lines (26 loc) · 2.61 KB

interactive-api-explorers.md

File metadata and controls

41 lines (26 loc) · 2.61 KB

Interactive API Explorers

The docs include an interactive explorer for some of the Camunda APIs. These explorers are generated with a Docusaurus plugin, based on an OpenAPI specification file.

Each explorer is configured in docusaurus.config.js (example). All API explorers are generated directly into the main docs instance.

The configuration can include multiple versions. The Next version docs are generated based on the spec located in the root api/[apiName] folder. Each numbered version's documentation is generated based on a spec located in the corresponding api/[apiName]/[version] folder.

As minor versions are released, the docs for the Next version are copied into the new "current" version of the docs. The docs team will adjust the configuration to also support documentation generation for this new version.

Source files

The source for each API's instance lives in an identifying folder within the /api folder. Following is a description of the contents of these folders.

  • /api/[apiName]/: Home to the API Explorer source/configuration.
  • /api/[apiName]/[apiName]-openapi.yaml: OpenAPI spec for vNext of the API.
  • /api/[apiName]/generation-strategy.js: A JavaScript file that describes custom steps required to standardize this API's explorer. See api/generate-api-docs for details on how this file is used during the generation process.
  • /api/[apiName]/[version]/[apiName]-openapi.yaml: OpenAPI spec for version [version] of the API.

Updating an OpenAPI spec

Regenerate the docs for the Next version of an API

  1. Replace the OpenAPI spec file at /api/[apiName]/[apiName]-openapi.yaml.
  2. Regenerate the docs with this command: npm run api:generate:[apiName]
  3. Commit the changes, and open a PR.

Regenerate the docs for a numbered version of an API

  1. Replace the OpenAPI spec file at /api/[apiName]/[version]/[apiName]-openapi.yaml.
  2. Regenerate the docs with this command: npm run api:generate:[apiName] [version]
  3. Commit the changes, and open a PR.

Code languages

Code languages in the interactive API Explorers are configured in the docusaurus.config.js.

The current languages have been chosen based on the popularity of existing clients. If you'd like to request a change to the currently included languages, please open an issue or reach out to the Developer Experience team.