Update API docs

[ddippolito]

Trello card URL

https://trello.com/c/c89aJ4g8/1447-documentation-of-api-for-users

Changes in this PR:

Add API documentation

[github-actions]

Review app deployed to https://teaching-vacancies-review-pr-7429.test.teacherservices.cloud on AKS

[scruti]

Nice! 👏

[scruti]

Nice. I left some suggestions for the current changes. Besides that there are 2 bits I would like to see added to the docs:

1. Put the docs behind user/password access.

So it doesn't get indexed by Google once it goes into production.
This can be configured on config/initializers/rswag_ui.rb (code to do so is commented). We need to set some user/password env variables for this config.

2. Changes in the vacancy API schema.

2.1 Extended descriptions/examples.

The vacancy schema needs to be extended so that every attribute in the schema has an example value & description.

Ideally, we would bring the "Purpose & Restrictions" info from the current V2 specification document as a "description" on the API schema fields.
The idea is to be sure that clients will understand what is the purpose of each field in plain English, and any restriction not reflected in the schema format.

This description will also be useful to indicate when we need "Choose one" or "One or more values from this list" besides the pure schematic formatting.

EG (the text is some random stuff for example):
expires_at: { type: :string, format: :date, example: "2025-03-13", description: "The end date of the vacancy. Must be after the start date." }

2.2 Schema inaccuracies.

Going through the fields, I noticed the schema needs to be updated to reflect our real restrictions.

Out of the scope of this PR, but we cannot start testing until we fix these. So happy to either fix them here or create a further ticket to address these:

So far noticed this one, but worth a double-check by multiple people in case I missed others:

• expires_at needs to be moved to date-time format.
  An oversight when we defined the schema for the first time, but allowing them to set an expiration time for the vacancies is a functionality we currently provide and probably want to keep.

[scruti]

Great improvements on the docs. LGTM!