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.

program/filters.py

@@ -3,7 +3,7 @@ import datetime
 from django_filters import rest_framework as filters
 from django_filters import widgets
 
-from django.contrib.auth.models import User
+from django import forms
 from django.db.models import Q, QuerySet
 from django.utils import timezone
 from program import models
@@ -19,18 +19,24 @@ class StaticFilterHelpTextMixin:
         return _filter
 
 
-class ModelMultipleChoiceFilter(filters.ModelMultipleChoiceFilter):
+class IntegerInFilter(filters.BaseInFilter):
+    class QueryArrayWidget(widgets.QueryArrayWidget):
+        # see: https://github.com/carltongibson/django-filter/issues/1047
+        def value_from_datadict(self, data, files, name):
+            new_data = {}
+            for key in data.keys():
+                if len(data.getlist(key)) == 1 and "," in data[key]:
+                    new_data[key] = data[key]
+                else:
+                    new_data[key] = data.getlist(key)
+            return super().value_from_datadict(new_data, files, name)
+
+    field_class = forms.IntegerField
+
     def __init__(self, *args, **kwargs):
-        kwargs.setdefault("widget", widgets.CSVWidget())
-        kwargs["lookup_expr"] = "in"
+        kwargs.setdefault("widget", self.QueryArrayWidget())
         super().__init__(*args, **kwargs)
 
-    def get_filter_predicate(self, v):
-        # There is something wrong with using ModelMultipleChoiceFilter
-        # along the CSVWidget that causes lookups to fail.
-        # May be related to: https://github.com/carltongibson/django-filter/issues/1103
-        return super().get_filter_predicate([v.pk])
-
 
 class ShowFilterSet(StaticFilterHelpTextMixin, filters.FilterSet):
     active = filters.BooleanFilter(
@@ -38,37 +44,34 @@ class ShowFilterSet(StaticFilterHelpTextMixin, filters.FilterSet):
         method="filter_active",
         help_text=(
             "Return only currently running shows (with timeslots in the future) if true "
-            "or past or upcoming shows if false.",
+            "or past or upcoming shows if false."
         ),
     )
-    host = ModelMultipleChoiceFilter(
-        queryset=models.Host.objects.all(),
+    host = IntegerInFilter(
         field_name="hosts",
         help_text="Return only shows assigned to the given host(s).",
     )
     # TODO: replace `musicfocus` with `music_focus` when dashboard is updated
-    musicfocus = ModelMultipleChoiceFilter(
-        queryset=models.MusicFocus.objects.all(),
+    musicfocus = IntegerInFilter(
         field_name="music_focus",
         help_text="Return only shows with given music focus(es).",
     )
-    owner = ModelMultipleChoiceFilter(
-        queryset=User.objects.all(),
+    owner = IntegerInFilter(
         field_name="owners",
         help_text="Return only shows that belong to the given owner(s).",
     )
-    category = ModelMultipleChoiceFilter(
-        queryset=models.Category.objects.all(),
+    category = IntegerInFilter(
         help_text="Return only shows of the given category or categories.",
     )
-    language = ModelMultipleChoiceFilter(
-        queryset=models.Language.objects.all(),
+    language = IntegerInFilter(
         help_text="Return only shows of the given language(s).",
     )
-    topic = ModelMultipleChoiceFilter(
-        queryset=models.Topic.objects.all(),
+    topic = IntegerInFilter(
         help_text="Return only shows of the given topic(s).",
     )
+    type = IntegerInFilter(
+        help_text="Return only shows of a given type.",
+    )
     public = filters.BooleanFilter(
         field_name="is_public",
         help_text="Return only shows that are public/non-public.",
@@ -102,9 +105,6 @@ class ShowFilterSet(StaticFilterHelpTextMixin, filters.FilterSet):
 
     class Meta:
         model = models.Show
-        help_texts = {
-            "type": "Return only shows of a given type.",
-        }
         fields = [
             "active",
             "category",
@@ -213,14 +213,12 @@ class TimeSlotFilterSet(filters.FilterSet):
 
 
 class NoteFilterSet(StaticFilterHelpTextMixin, filters.FilterSet):
-    ids = ModelMultipleChoiceFilter(
+    ids = IntegerInFilter(
         field_name="id",
-        queryset=models.Note.objects.all(),
         help_text="Return only notes matching the specified id(s).",
     )
-    owner = ModelMultipleChoiceFilter(
+    owner = IntegerInFilter(
         field_name="show__owners",
-        queryset=models.User.objects.all(),
         help_text="Return only notes by show the specified owner(s): all notes the user may edit.",
     )