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.

steering/settings.py

@@ -109,6 +109,19 @@ REST_FRAMEWORK = {
         "program.auth.OidcOauth2Auth",
     ],
     "DEFAULT_FILTER_BACKENDS": ["django_filters.rest_framework.DjangoFilterBackend"],
+    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+    "EXCEPTION_HANDLER": "steering.views.full_details_exception_handler",
+}
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "AURA Steering API",
+    "DESCRIPTION": "Programme/schedule management for Aura",
+    "POSTPROCESSING_HOOKS": [
+        "drf_spectacular.hooks.postprocess_schema_enums",
+        "steering.schema.add_enum_documentation",
+        "steering.schema.fix_schedule_pk_type",
+    ],
+    "VERSION": "1.0.0",
 }
 
 INSTALLED_APPS = (
@@ -125,6 +138,7 @@ INSTALLED_APPS = (
     "rest_framework",
     "rest_framework_nested",
     "django_filters",
+    "drf_spectacular",
     "oidc_provider",
     "corsheaders",
 )