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/serializers.py

@@ -20,6 +20,7 @@
 
 from profile.models import Profile
 from profile.serializers import ProfileSerializer
+from typing import List
 
 from rest_framework import serializers
 
@@ -44,6 +45,37 @@ from program.models import (
 from program.utils import get_audio_url
 from steering.settings import THUMBNAIL_SIZES
 
+SOLUTION_CHOICES = {
+    "theirs": "Discard projected timeslot. Keep existing timeslot(s).",
+    "ours": "Create projected timeslot. Delete existing timeslot(s).",
+    "theirs-start": (
+        "Keep existing timeslot. Create projected timeslot with start time of existing end."
+    ),
+    "ours-start": (
+        "Create projected timeslot. Change end of existing timeslot to projected start time."
+    ),
+    "theirs-end": (
+        "Keep existing timeslot. Create projected timeslot with end of existing start time."
+    ),
+    "ours-end": (
+        "Create projected timeslot. Change start of existing timeslot to projected end time."
+    ),
+    "theirs-both": (
+        "Keep existing timeslot. "
+        "Create two projected timeslots with end of existing start and start of existing end."
+    ),
+    "ours-both": (
+        "Create projected timeslot. Split existing timeslot into two: \n\n"
+        "* set existing end time to projected start,\n"
+        "* create another timeslot with start = projected end and end = existing end."
+    ),
+}
+
+
+class ErrorSerializer(serializers.Serializer):
+    message = serializers.CharField()
+    code = serializers.CharField(allow_null=True)
+
 
 class UserSerializer(serializers.ModelSerializer):
     # Add profile fields to JSON
@@ -139,10 +171,10 @@ class LinkSerializer(serializers.ModelSerializer):
 
 class HostSerializer(serializers.ModelSerializer):
     links = LinkSerializer(many=True, required=False)
-    thumbnails = serializers.SerializerMethodField()  # Read-only
+    thumbnails = serializers.SerializerMethodField()
 
     @staticmethod
-    def get_thumbnails(host):
+    def get_thumbnails(host) -> List[str]:
         """Returns thumbnails"""
         thumbnails = []
 
@@ -261,10 +293,10 @@ class ShowSerializer(serializers.HyperlinkedModelSerializer):
     predecessor = serializers.PrimaryKeyRelatedField(
         queryset=Show.objects.all(), required=False, allow_null=True
     )
-    thumbnails = serializers.SerializerMethodField()  # Read-only
+    thumbnails = serializers.SerializerMethodField()
 
     @staticmethod
-    def get_thumbnails(show):
+    def get_thumbnails(show) -> List[str]:
         """Returns thumbnails"""
         thumbnails = []
 
@@ -372,14 +404,44 @@ class ShowSerializer(serializers.HyperlinkedModelSerializer):
 
 
 class ScheduleSerializer(serializers.ModelSerializer):
-    rrule = serializers.PrimaryKeyRelatedField(queryset=RRule.objects.all())
-    show = serializers.PrimaryKeyRelatedField(queryset=Show.objects.all())
+    rrule = serializers.PrimaryKeyRelatedField(
+        queryset=RRule.objects.all(),
+        help_text=Schedule.rrule.field.help_text,
+    )
+    show = serializers.PrimaryKeyRelatedField(
+        queryset=Show.objects.all(),
+        help_text=Schedule.show.field.help_text,
+    )
     # TODO: remove this when the dashboard is updated
-    byweekday = serializers.IntegerField(source="by_weekday")
-    dstart = serializers.DateField(source="first_date")
-    tstart = serializers.TimeField(source="start_time")
-    tend = serializers.TimeField(source="end_time")
-    until = serializers.DateField(source="last_date")
+    byweekday = serializers.IntegerField(
+        source="by_weekday",
+        help_text=Schedule.by_weekday.field.help_text,
+    )
+    dstart = serializers.DateField(
+        source="first_date",
+        help_text=Schedule.first_date.field.help_text,
+    )
+    tstart = serializers.TimeField(
+        source="start_time",
+        help_text=Schedule.start_time.field.help_text,
+    )
+    tend = serializers.TimeField(
+        source="end_time",
+        help_text=Schedule.end_time.field.help_text,
+    )
+    until = serializers.DateField(
+        source="last_date",
+        help_text=Schedule.last_date.field.help_text,
+    )
+    dryrun = serializers.BooleanField(
+        write_only=True,
+        required=False,
+        help_text=(
+            "Whether to simulate the database changes. If true, no database changes will occur. "
+            "Instead a list of objects that would be created, updated and deleted if dryrun was "
+            "false will be returned."
+        ),
+    )
 
     class Meta:
         model = Schedule
@@ -423,6 +485,88 @@ class ScheduleSerializer(serializers.ModelSerializer):
         return instance
 
 
+class CollisionSerializer(serializers.Serializer):
+    id = serializers.IntegerField()
+    start = serializers.DateTimeField()
+    end = serializers.DateTimeField()
+    playlist_id = serializers.IntegerField(allow_null=True)
+    show = serializers.IntegerField()
+    show_name = serializers.CharField()
+    is_repetition = serializers.BooleanField()
+    schedule = serializers.IntegerField()
+    memo = serializers.CharField()
+    note_id = serializers.IntegerField(allow_null=True)
+
+
+class ProjectedTimeSlotSerializer(serializers.Serializer):
+    hash = serializers.CharField()
+    start = serializers.DateTimeField()
+    end = serializers.DateTimeField()
+    collisions = CollisionSerializer(many=True)
+    error = serializers.CharField(allow_null=True)
+    solution_choices = serializers.ListField(
+        child=serializers.ChoiceField(SOLUTION_CHOICES)
+    )
+
+
+class DryRunTimeSlotSerializer(serializers.Serializer):
+    id = serializers.PrimaryKeyRelatedField(
+        queryset=TimeSlot.objects.all(), allow_null=True
+    )
+    schedule = serializers.PrimaryKeyRelatedField(
+        queryset=Schedule.objects.all(), allow_null=True
+    )
+    playlist_id = serializers.IntegerField(allow_null=True)
+    start = serializers.DateField()
+    end = serializers.DateField()
+    is_repetition = serializers.BooleanField()
+    memo = serializers.CharField()
+
+
+class ScheduleCreateUpdateRequestSerializer(serializers.Serializer):
+    schedule = ScheduleSerializer()
+    solutions = serializers.DictField(child=serializers.ChoiceField(SOLUTION_CHOICES))
+    notes = serializers.DictField(child=serializers.IntegerField(), required=False)
+    playlists = serializers.DictField(child=serializers.IntegerField(), required=False)
+
+
+# TODO: There shouldn’t be a separate ScheduleSerializer for use in responses.
+#       Instead the default serializer should be used. Unfortunately, the
+#       code that generates the data creates custom dicts with this particular format.
+class ScheduleInResponseSerializer(serializers.Serializer):
+    # "Schedule schema type" is the rendered name of the ScheduleSerializer.
+    """
+    For documentation on the individual fields see the
+    Schedule schema type.
+    """
+    add_business_days_only = serializers.BooleanField()
+    add_days_no = serializers.IntegerField(allow_null=True)
+    by_weekday = serializers.IntegerField()
+    default_playlist_id = serializers.IntegerField(allow_null=True)
+    end_time = serializers.TimeField()
+    first_date = serializers.DateField()
+    id = serializers.PrimaryKeyRelatedField(queryset=Schedule.objects.all())
+    is_repetition = serializers.BooleanField()
+    last_date = serializers.DateField()
+    rrule = serializers.PrimaryKeyRelatedField(queryset=RRule.objects.all())
+    show = serializers.PrimaryKeyRelatedField(queryset=Note.objects.all())
+    start_time = serializers.TimeField()
+
+
+class ScheduleConflictResponseSerializer(serializers.Serializer):
+    projected = ProjectedTimeSlotSerializer(many=True)
+    solutions = serializers.DictField(child=serializers.ChoiceField(SOLUTION_CHOICES))
+    notes = serializers.DictField(child=serializers.IntegerField())
+    playlists = serializers.DictField(child=serializers.IntegerField())
+    schedule = ScheduleInResponseSerializer()
+
+
+class ScheduleDryRunResponseSerializer(serializers.Serializer):
+    created = DryRunTimeSlotSerializer(many=True)
+    updated = DryRunTimeSlotSerializer(many=True)
+    deleted = DryRunTimeSlotSerializer(many=True)
+
+
 class TimeSlotSerializer(serializers.ModelSerializer):
     show = serializers.PrimaryKeyRelatedField(queryset=Show.objects.all())
     schedule = serializers.PrimaryKeyRelatedField(queryset=Schedule.objects.all())
@@ -452,11 +596,10 @@ class NoteSerializer(serializers.ModelSerializer):
     show = serializers.PrimaryKeyRelatedField(queryset=Show.objects.all())
     timeslot = serializers.PrimaryKeyRelatedField(queryset=TimeSlot.objects.all())
     host = serializers.PrimaryKeyRelatedField(queryset=Host.objects.all())
-    thumbnails = serializers.SerializerMethodField()  # Read-only
-    cba_id = serializers.IntegerField(required=False, write_only=True)
+    thumbnails = serializers.SerializerMethodField()
 
     @staticmethod
-    def get_thumbnails(note):
+    def get_thumbnails(note) -> List[str]:
         """Returns thumbnails"""
         thumbnails = []