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
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
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:
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
You can also manually validate the document, running:
If you have Visual Studio Code, we suggest you install the following extensions that enable validation and navigation within the spec file: