Skip to main content

Contributing to the API Specification Docs

important

We’re currently making rapid changes to the product so our docs may be out of date. If you need help, please email yo@forem.com.

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: