Add API documentation
Compare changes
Files
1- Konrad Mohrfeldt authored
This gives the calling code better control over the handling of such errors and makes it easy to differentiate between errors and valid return types.
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.400
HTTP status code instead of 201
.202
HTTP status code instead of 201
.note_id
property on a schedule collision object will always be present but may be null
. It was omitted in some cases.error
property on a projected timeslot will always be present but may be null
. It was omitted in some cases.Notes & Caveats:
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.This gives the calling code better control over the handling of such errors and makes it easy to differentiate between errors and valid return types.