Add API documentation

This MR implements an auto-generated API documentation with drf-spectacular.

As the steering API uses a lot of subpath resources a few changes are necessary in order to make documentation feasible. As some of these changes are quite invasive (in the sense that they replace a lot of custom with generic logic) we should invest in a little bit of testing before this is merged.

Depending on the remaining time I can spent on this issue, I will implement these myself.

Possibly breaking changes in the external API:

• APIException objects are now converted to error lists in the form of [ { "message: "a message", "code": "an optional code" } ] making them easier to handle for client code (see c9164158). This also affects the hard errors raised during schedule creation/updates.
• Hard errors raised during schedule creation/updates now return a 400 HTTP status code instead of 201.
• A schedule submitted as a dryrun now returns a 202 HTTP status code instead of 201.
• The note_id property on a schedule collision object will always be present but may be null. It was omitted in some cases.
• The error property on a projected timeslot will always be present but may be null. It was omitted in some cases.

Notes & Caveats:

• The serializers for the scheduling responses are only used for documentation purposes. The scheduling code should probably be refactored to actually depend on those serializers to generate API responses.
• Enums auto-generated by drf-spectacular come with no documentation even though the choices they are generated from may have some. This is the case for the by_weekday attribute of the Schedule instance, as well as the solution_choices attribute of CollisionSerializer and the solutions attribute of the ScheduleCreateUpdateRequestSerializer. I’ve decided to manually patch the generated enums in post-processing as the context information provided by the choice descriptions seems vital to me. It might be a good idea to invest some time into drf-spectacular and send a pull-request upstream so that manual patching can be dropped as one might easily miss this when adding new or changing existing code. See steering/schema.py.

.gitlab-ci.yml

@@ -7,8 +7,28 @@
       - Dockerfile
 
 stages:
+  - build
   - release
 
+build-openapi-scheme:
+  image: python:3.9-alpine
+  variables:
+    SECRET_KEY: not-a-very-secret-key
+    DJANGO_SETTINGS_MODULE: steering.settings
+    # steering.settings switches to sqlite if the VIRTUAL_ENV environment
+    # variable is present. It’s probably a good idea to refactor this to
+    # something more explicit.
+    VIRTUAL_ENV: 1
+  before_script:
+    - apk add gcc musl-dev zlib-dev jpeg-dev libmagic
+    - pip install -r requirements.txt
+  script:
+    - python3 -m django spectacular --validate --lang en --file openapi.yaml
+  artifacts:
+    paths:
+      - openapi.yaml
+
+
 docker-push:
   # Use the official docker image.
   image: docker:latest
@@ -32,16 +52,16 @@ docker-push:
       fi
     # TODO: maybe isolate docker build and docker push
     - docker push "$AURA_IMAGE_NAME" --all-tags
-  rules: 
+  rules:
     - *release-rules
     # every commit on master/main branch should trigger a push to docker-hub as unstable without a release
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH 
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
       exists:
         - Dockerfile
 
 release_job:
   stage: release
-  needs: 
+  needs:
     - docker-push
   image: registry.gitlab.com/gitlab-org/release-cli:latest
   rules: *release-rules