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.
