rootstrap/rails_api_base

# 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](https://stackoverflow.com/a/74563109):
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`
```ruby
  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:
```ruby
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:
```diff
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:
```diff
-  name: Upload partial API Docs
-  if: ${{ env.OPENAPI }}
```