chore(release): 0.10.0

See merge request !67

feat: move to upstream OpenAPI generator template

Closes #22

See merge request !68

Now that uis/devops/continuous-delivery/ci-templates#93 is closed, we
have a generic OpenAPI generator template. Make use of it.

Closes #22

auto-generate API clients, package them, publish them and publish docs to GitLab pages

See merge request !66

The common CI pipeline has support for mkdocs-based documentation and so
add a basic generated mkdocs config. Base the mkdocs config on the
config which is likely to land in the copier template to minimise future
disruption.

We need to override some parts of the standard jobs to "inject" the
documentation generated by the OpenAPI templates into them. We also need
to add "fake" index.html files which take the place of the real
documentation which will be injected in.

Add jobs which publish generated OpenAPI clients to GitLab's own package
registry. In time we may add ones which publish directly to npm and/or
PyPI but for the moment keep things simple.

Packages are only published if the git ref name matches a specific
value. By default it is the default branch but it can be customised for
advanced users.

Generate documentation for each of the OpenAPI clients along with
redoc-based documentation for the schema itself. Downstream projects
should arrange to copy this documentation to some appropriate place.

We add generic "document a TypeScript project" and "document a Python
project" jobs along with specialisations for each of the clients we
generate.

All documentation ends up in `OPENAPI_GENERATOR_DOCS_ARTIFACT_DIR` which
can be overridden by consuming projects.

Use the openapi-generator CLI to generate and package a TypeScript
client using axios for HTTP transport and a Python package using urllib3
for transport. The version numbers of the generated packages match the
version number of the generated OpenAPI schema.

As the OpenAPI generator is intended to be generic, we configure a
reasonable set of defaults for generated artefact names, etc. Show how
these can be customised in local configuration to specify alternate
locations for schema files and source packages to be added as release
assets. Add the generated API clients as release assets.

The list of generated clients is supposed to be slightly opaque to the
consuming project so that we may add additional clients over time.
Should that prove troublesome, each client may be explicitly disabled by
setting a generator-specific `..._DISABLED` variable.

The package name is generated from the GitLab project name but can be
overridden. We do so in our case since the project name ("api") is a
little under-descriptive.

As with generation, we support per-client overriding of the package name
which we demonstrate with the Python package.

If the schema hasn't changed, not only is it not worth re-generating
clients but we also won't be able to publish clients using the default
strategy of extracting the version from the schema. (Both PyPI and npm
disallow re-uploading packages with the same version number.)

The flake8 pre-commit checker was moaning about some files due to not
understanding modern f-string idiom. Update it.

There was no LICENSE file present and some of the docstrings either did
not match the annotated return types or were otherwise malformed. Fix
these small warts.

chore(release): 0.9.4

See merge request !65

fix: disable release assets for the moment

See merge request !64

While we work out the correct incantation/version of release-it to
successfully upload releases, disable release assets for the time being
to unblock future releases.

chore(release): 0.9.2

See merge request !63

fix: tall release-it we are using a later GitLab

See merge request !62

According to [the release-it docs][1], we need to specify
"useIdsForUrls" when using assets with GitLab versions after 17.2.

Do so.

[1]: https://github.com/release-it/release-it/blob/main/docs/gitlab-releases.md#attach-binary-assets

chore(release): 0.9.1

See merge request !61

fix: configure release-it with correct openapi asset name

See merge request !60

Although we're generating the OpenAPI schema in "openapi.yaml", we were
telling release-it to look for "openapi.yml" which [it could not
find][1].

[1]: https://gitlab.developers.cam.ac.uk/uis/devops/iam/activate-account/api/-/jobs/1913998#L56

chore(release): 0.9.0

See merge request !59

feat: add OpenAPI schema to release artefacts

See merge request !58

Use release-it's release assets feature to add the build OpenAPI schema
to the release assets. Formally speaking the location of the OpenAPI
artefacts is not guaranteed and so we explicitly set the location of the
artifacts we use before adding it to the release-it configuration.

chore(release): 0.8.0

See merge request !57

feat: add the bones of an OpenAPI client generation mechanism

Closes #24

See merge request !56

Add the start of a re-usable OpenAPI client generation mechanism. Add
two files: one which represents the repository-local customisation and
one which is the re-usable template. Add the start of some documentation
for the template with an eye to moving it to the guidebook.

The general idea is that getting OpenAPI clients *should* be as simple
as including an `openapi.yaml` file in the root of the repository. (Note
the name of the file was chosen because GitLab will automatically render
files so-named with swagger UI.)

For our specific use case we want to generate the schema dynamically and
so allow for this by means of customising an "openapi:schema" job whose
role is to ensure the schema is available to downstream jobs as a CI job
artefact. The default behaviour is simply to copy the schema from the
repository but we override it to use the DRF spectactular Django
management command. We use the `--fail-if-warn` flag to allow this job
to additionally act as a "test" test that schema generation succeeds
without warning.

Add in the plumbing to run the [openapi-generator CLI][1] but only use
it for the moment as an additional "test" job which validates the spec.

[1]: https://openapi-generator.tech/

The template has been written with an eye to adding to the common
pipeline and so that there can be zero configuration required to make
use of it. As such the template follows the rules of the common pipeline
in being "safe" to include with no side-effects unless it's triggered
and all CI variables and artefacts are appropriately namespaced.

Closes #24

chore(release): 0.7.0

See merge request !54