Skip to content
Snippets Groups Projects

Add API documentation

Merged Add API documentation
feature/api-docs into master
Merged Konrad Mohrfeldt requested to merge feature/api-docs into master

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.
Edited by Konrad Mohrfeldt

Merge request reports

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
Please register or sign in to reply