4c6b901b7a
* Add @stoplight/spectral to dev dependencies for validation * Add yarn api-docs:lint command * Fix linting errors * Lower severity level * Add ibm-openapi-validator as linter, as it inspects slightly differently
1.5 KiB
| title |
|---|
| Contributing to the API Specification Docs |
Contributing to API specification docs
The API v0 is described with the OpenAPI 3 specification.
Where you can find the spec file
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.
Updating API docs
Whenever you make changes to the API docs, make sure to bump the version at the
top of api_v0.yml, in info.version.
Running and editing the docs locally
If you want to browse the documentation locally you can use:
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.
Linting and validation
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:
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: