api_documentation.md

API Docs

Generating Docs

Docs are autogenerated based off of the requests specs, no extra code is needed.

The specs are run with the OPENAPI env var set to trigger the doc generation, it is set on pushes only in the main branch and when changes are made to spec/requests/api.

For the action to update the docs make sure to set the PUSH_KEY secret so the CI can update the docs. To do so follow these steps:

1. Run locally ssh-keygen -N "" -f deploy_key -C "github-actions".
2. Add a "secret" to the repo with name PUSH_KEY and value the generated file deploy_key.
3. Add a "deploy key" to the repo with title GitHub Actions and value the generated file deploy_key.pub. Make sure to tick the "Allow write access" checkbox.

SwaggerUI

The autogenerated documentation is exposed using Swagger UI, this documentation can be found in the /api-docs path.

The route is protected using basic auth by default, this can be disabled in the initializer file rswag_ui.rb

  c.basic_auth_enabled = true
  c.basic_auth_credentials ENV.fetch('SWAGGER_USERNAME', 'username'), ENV.fetch('SWAGGER_PASSWORD', 'password')

the access data can also be defined using the environment variables SWAGGER_USERNAME and SWAGGER_PASSWORD.

Ignoring specs

To ignore specs that we don't want in the final API documentation we can add the openapi: false option to the spec like so:

describe 'GET admin/feature-flags', openapi: false do

Labeling

An autolabeler action takes care of labeling with api_docs for any PR that changes the spec/requests/api files.

The label has to be created before hand for the labeler to work

Parallelization

All request specs are ran parallelized in different nodes with N threads each. Each thread produces a piece of the updated doc file, which we then merge and upload. After each node uploads its piece of the update doc we download all of them and merge them together into the final file.

Removing CI action

If you wish not to have a specific action to update the docs for you in the CI you can just modify the file and remove the following steps and jobs:

jobs:
...
  tests:
    ...
    steps:
-     - name: Set ENV for api docs
      ...
-     - name: Merge API docs from threads
  ...
- merge_results:
    ...

Also remove any step that has the OPENAPI env var:

-  name: Upload partial API Docs
-  if: ${{ env.OPENAPI }}