8c4fd87599
* Update contributing guide In this change, I tried to simplify the language of the contributing guide to make it more accessible and less wordy. I also updated the information in a few places and fixed a couple of typos. * Remove table of contents Since moving this doc to the docs site, our theme generates a ToC automatically, hardcoding this one is redundant. * Move the contributing guides * Update maintainer documentation This chnage updates the maintainers guide to include information on PR reviews, deployments, and CI. Housing this documentation here increases transparency with our community. * Edit with PR feedback * Edit based on PR feedback
1.7 KiB
| title |
|---|
| Contributing to the API Specification Docs |
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.
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: