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 of201
. - A schedule submitted as a dryrun now returns a
202
HTTP status code instead of201
. - The
note_id
property on a schedule collision object will always be present but may benull
. It was omitted in some cases. - The
error
property on a projected timeslot will always be present but may benull
. 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 theSchedule
instance, as well as thesolution_choices
attribute ofCollisionSerializer
and thesolutions
attribute of theScheduleCreateUpdateRequestSerializer
. 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.
Edited by Konrad Mohrfeldt