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
52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
---
|
|
title: Contributing to the API Specification Docs
|
|
---
|
|
|
|
# Contributing to API specification docs
|
|
|
|
The API v0 is described with the
|
|
[OpenAPI 3 specification](https://spec.openapis.org/oas/v3.0.3).
|
|
|
|
Swagger.io has
|
|
[great docs](https://swagger.io/docs/specification/basic-structure/) 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](https://github.com/Redocly/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:
|
|
|
|
```shell
|
|
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](https://github.com/stoplightio/spectral) and
|
|
[ibm-openapi-validator](https://github.com/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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
- [OpenAPI (Swagger) editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
|
|
- [openapi-designer live preview](https://marketplace.visualstudio.com/items?itemName=philosowaffle.openapi-designer)
|