Skip to main content

Contributing to the API Specification Docs

The v0 and v1 APIs are described with the OpenAPI 3 specification. has great docs that are helpful to understand the specification better.

Where you can find the spec file

We auto-generate the v0 documentation from api_v0.yml, and v1 documentation from the api_v1.json, both located within the /docs directory. We use ReDoc to turn the OpenAPI 3 format into a readable and searchable HTML documentation.

Updating API docs

There should be very infrequent reasons to update the v0 documentation. If must make changes to the v0 API docs, make sure to bump the version at the top of api_v0.yml, in info.version.

v1 API documentation is generated from the file api_v1.json which is generated via the Forem source code via the rswag gem. To add to the documentation: create or add to an existing documentation test under spec/requests/api/v1/docs. Run the documentation suite via the command

SWAGGER_DRY_RUN=0 RAILS_ENV=test rails rswag PATTERN="spec/requests/api/v1/docs/*_spec.rb"

An OpenAPI 3 spec file will be generated at swagger/v1/api_v1.json. Copy this file to the root of the forem-docs project, then refer to the forem-docs readme to rebuild the documentation site.

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: