Contributing to API specification docs

The API v0 is described with the OpenAPI 3 specification.

Swagger.io has great docs that are helpful to understand the specification better.

We auto-generate the documentation from api_v0.yml within the /docs directory. We use ReDoc to turn the OpenAPI 3 format into a readable and searchable HTML documentation.

Whenever you make changes to the API docs, make sure to bump the version at the top of api_v0.yml, in info.version.

If you want to browse the documentation locally you can use:

1
yarn api-docs:serve

This will let you browse the auto-generated version of the doc locally, and it will reload the documentation after every change of the specification file.

We use spectral and ibm-openapi-validator to validate the spec file. The validation is performed as a pre-commit hook.

You can also manually validate the document, running:

1
yarn api-docs:lint

If you have Visual Studio Code, we suggest you install the following extensions that enable validation and navigation within the spec file:

• OpenAPI (Swagger) editor
• openapi-designer live preview