Contributing to the API Specification Docs
The v0 and v1 APIs are 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 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: