Add mechanism to generate OpenAPI specification

Description

We want to ensure the OpenAPI specification is available in the pipelines for downstream use in CI, and other downstream systems

Further details

There are two ways we could achieve this:

1. Ensure the OpenAPI specification is generated and stored in the repository root
2. Generate the OpenAPI specification in the pipeline, and add it as a release asset

Opt 1, Generate and Check-In

Required work:

• Check in OpenAPI specification.
• Add (local, for now) pre-commit hook to ensure it is kept up to date.

Opt 2, Generate in Pipeline

Required work:

• Add build step pipeline to generate OpenAPI and store as build artefact (set expiration of build artefact to 0, see https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html#with-an-expiry)
• Add release step pipeline to add the OpenAPI specification build artefact to a release as an asset.

These pipeline jobs would be defined under .gitlab directory, for later extraction to CI-templates.

We're going with option 2 for this task as decided in tech refinement

Task list

Acceptance criteria

• Pipeline in build stage, running in merge request pipelines and release pipelines generates OpenAPI specification and stores as build artefact
• Release pipeline pulls in OpenAPI from artefacts and includes OpenAPI specification as an asset, running only on release pipelines
• Issue raised in ci-templates repository to move these jobs out into a template

Links/references