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

@@ -4,7 +4,6 @@ from django_filters import rest_framework as filters
 from django_filters import widgets
 
 from django import forms
-from django.contrib.auth.models import User
 from django.db.models import Q, QuerySet
 from django.utils import timezone
 from program import models
@@ -20,55 +19,59 @@ 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(
         field_name="is_active",
         method="filter_active",
         help_text=(
-            "Return only currently running shows if true or past or upcoming shows if false.",
+            "Return only currently running shows (with timeslots in the future) if true "
+            "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",
@@ -182,16 +182,10 @@ class TimeSlotFilterSet(filters.FilterSet):
             queryset = self.filter_surrounding(queryset, "surrounding", timezone.now())
         return queryset
 
-    class Meta:
-        model = models.TimeSlot
-        fields = [
-            "order",
-            "start",
-            "end",
-            "surrounding",
-        ]
+    def get_form_class(self):
+        form_cls = super().get_form_class()
 
-        class form(forms.Form):
+        class TimeSlotFilterSetFormWithDefaults(form_cls):
             def clean_start(self):
                 start = self.cleaned_data.get("start", None)
                 return start or timezone.now().date()
@@ -200,16 +194,31 @@ class TimeSlotFilterSet(filters.FilterSet):
                 end = self.cleaned_data.get("end", None)
                 return end or self.cleaned_data["start"] + datetime.timedelta(days=60)
 
+        # We only want defaults to apply in the context of the list action.
+        # When accessing individual timeslots we don’t want the queryset to be restricted
+        # to the default range of 60 days as get_object would yield a 404 otherwise.
+        if self.request.parser_context["view"].action == "list":
+            return TimeSlotFilterSetFormWithDefaults
+        else:
+            return form_cls
+
+    class Meta:
+        model = models.TimeSlot
+        fields = [
+            "order",
+            "start",
+            "end",
+            "surrounding",
+        ]
+
 
 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.",
     )