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

@@ -19,9 +19,11 @@
 #
 
 from datetime import datetime, time, timedelta
+from textwrap import dedent
 
 from dateutil.relativedelta import relativedelta
 from dateutil.rrule import rrule
+from rest_framework.exceptions import ValidationError
 from versatileimagefield.fields import PPOIField, VersatileImageField
 
 from django.contrib.auth.models import User
@@ -224,17 +226,76 @@ class RRule(models.Model):
 
 
 class Schedule(models.Model):
-    rrule = models.ForeignKey(RRule, on_delete=models.CASCADE, related_name="schedules")
-    show = models.ForeignKey(Show, on_delete=models.CASCADE, related_name="schedules")
-    by_weekday = models.IntegerField()
-    first_date = models.DateField()
-    start_time = models.TimeField()
-    end_time = models.TimeField()
-    last_date = models.DateField()
-    is_repetition = models.BooleanField(default=False)
-    add_days_no = models.IntegerField(blank=True, null=True)
-    add_business_days_only = models.BooleanField(default=False)
-    default_playlist_id = models.IntegerField(blank=True, null=True)
+    rrule = models.ForeignKey(
+        RRule,
+        on_delete=models.CASCADE,
+        related_name="schedules",
+        help_text=dedent(
+            """
+            A recurrence rule.
+
+            * 1 = once,
+            * 2 = daily,
+            * 3 = business days,
+            * 4 = weekly,
+            * 5 = biweekly,
+            * 6 = every four weeks,
+            * 7 = every even calendar week (ISO 8601),
+            * 8 = every odd calendar week (ISO 8601),
+            * 9 = every 1st week of month,
+            * 10 = every 2nd week of month,
+            * 11 = every 3rd week of month,
+            * 12 = every 4th week of month,
+            * 13 = every 5th week of month
+            """
+        ),
+    )
+    show = models.ForeignKey(
+        Show,
+        on_delete=models.CASCADE,
+        related_name="schedules",
+        help_text="Show the schedule belongs to.",
+    )
+    by_weekday = models.IntegerField(
+        help_text="Number of the Weekday.",
+        choices=[
+            (0, "Monday"),
+            (1, "Tuesday"),
+            (2, "Wednesday"),
+            (3, "Thursday"),
+            (4, "Friday"),
+            (5, "Saturday"),
+            (6, "Sunday"),
+        ],
+    )
+    first_date = models.DateField(help_text="Start date of schedule.")
+    start_time = models.TimeField(help_text="Start time of schedule.")
+    end_time = models.TimeField(help_text="End time of schedule.")
+    last_date = models.DateField(help_text="End date of schedule.")
+    is_repetition = models.BooleanField(
+        default=False,
+        help_text="Whether the schedule is a repetition.",
+    )
+    add_days_no = models.IntegerField(
+        blank=True,
+        null=True,
+        help_text=(
+            "Add a number of days to the generated dates. "
+            "This can be useful for repetitions, like 'On the following day'."
+        ),
+    )
+    add_business_days_only = models.BooleanField(
+        default=False,
+        help_text=(
+            "Whether to add add_days_no but skipping the weekends. "
+            "E.g. if weekday is Friday, the date returned will be the next Monday."
+        ),
+    )
+    default_playlist_id = models.IntegerField(
+        blank=True,
+        null=True,
+        help_text="A tank ID in case the timeslot's playlist_id is empty.",
+    )
 
     class Meta:
         ordering = ("first_date", "start_time")
@@ -525,10 +586,10 @@ class Schedule(models.Model):
 
                 # Get note
                 try:
-                    note = Note.objects.get(timeslot=c.id).values_list("id", flat=True)
-                    collision["note_id"] = note
+                    note = Note.objects.get(timeslot=c.id)
+                    collision["note_id"] = note.pk
                 except ObjectDoesNotExist:
-                    pass
+                    collision["note_id"] = None
 
                 collisions.append(collision)
 
@@ -606,6 +667,7 @@ class Schedule(models.Model):
 
             projected_entry["collisions"] = collisions
             projected_entry["solution_choices"] = solution_choices
+            projected_entry["error"] = None
             projected.append(projected_entry)
 
         conflicts["projected"] = projected
@@ -673,17 +735,26 @@ class Schedule(models.Model):
         conflicts = Schedule.make_conflicts(sdl, schedule_pk, show_pk)
 
         if schedule.rrule.freq > 0 and schedule.first_date == schedule.last_date:
-            return {"detail": _("Start and until dates mustn't be the same")}
+            raise ValidationError(
+                _("Start and until dates mustn't be the same"),
+                code="no-same-day-start-and-end",
+            )
 
         if schedule.last_date < schedule.first_date:
-            return {"detail": _("Until date mustn't be before start")}
+            raise ValidationError(
+                _("Until date mustn't be before start"),
+                code="no-start-after-end",
+            )
 
         num_conflicts = len(
             [pr for pr in conflicts["projected"] if len(pr["collisions"]) > 0]
         )
 
         if len(solutions) != num_conflicts:
-            return {"detail": _("Numbers of conflicts and solutions don't match.")}
+            raise ValidationError(
+                _("Numbers of conflicts and solutions don't match."),
+                code="one-solution-per-conflict",
+            )
 
         # Projected timeslots to create
         create = []