Skip to content

Use drf-spectacular for OpenAPI schemas

Erwan Rouchetrequested to merge
drf-spectacular into master

This replaces the existing schema generation hacks with different schema generation hacks: drf-spectacular is used to provide a more compact and better support for endpoint overriding, while still keeping support for the two previous overriding systems (patch.yml and openapi_overrides).

Requires ponos!213 and api-client!200 (merged)

Closes #53 (closed), closes #86 (closed), closes #87 (closed), closes #255 (closed), closes #256 (closed), closes #257 (closed), closes #491 (closed), closes #545 (closed) 💥

TODO

  • Plug drf-spectacular in
  • Add to CI
  • Restore patch.yml support
  • Restore openapi_overrides support
  • Restore PascalCase operation IDs
  • Restore DeprecatedMixin
  • Restore SearchAutoSchema
  • Restore x-name on request bodies
  • Add check for endpoint tags
  • Fix all reported warnings and errors
    • Fix 'Unable to guess serializer' errors
    • Fix SerializerMethodField and @property typings
    • Resolve enum collisions
    • Fix path parameter typings
    • Fix 'Failed to obtain model' warnings
    • Undefined tags warnings
    • Upstream issue for false positives on component re-registration warnings
    • Fix Ponos-related warnings using extensions
  • Fix operation ID generation
    • Spectacular's logic generates WorkerVersionCreate.
    • Reapplying DRF's original logic instead generates duplicate names like ListElements4 and DestroyElement3 or dumb names like CreateElementCreate.
  • Write OpenApiViewExtension classes to customize Ponos endpoints, or directly subclass the original views
    • Add simple type hints to Ponos ponos!213
  • Fix OpenAPI unit tests
  • Test with the API client
  • Diff the whole schema
  • Backwards compatibility for ?format=openapi-json
  • Test all tasks in arkindex/tasks
    • image import
    • pdf import
    • pdf import with text extraction
    • thumbnails
    • transkribus
    • git IIIF import
    • git worker import
    • IIIF import from datafile
  • Test with at least 1 worker
    • init elements
    • tesseract
    • spacy
  • Rebase, ouch
  • Update https://wiki.vpn/en/arkindex/dev-doc/openapi

Migration notes

  • After some testing, it seems going view by view instead of first destroying patch.yml then openapi_overrides is the easiest option; if an endpoint simultaneously has spectacular extensions, overrides and patches, there can be strange interactions.
  • It seems the easiest for Ponos overrides will be to subclass Ponos API views directly, like in !1066 (merged), to apply extend_schema on them.
  • It has been pointed out that all those decorators will make already long API endpoint modules even longer, so we should consider splitting them and reorganizing them in api.metadata, api.elements, api.corpus, api.entities, api.transcriptions, api.classifications, …
  • The docs on most endpoints can be later heavily enhanced, for example for endpoints with serializers that have different, or to better document error handling.

ｓｐｅｃｔａｃｕｌａｒ

Edited by Erwan Rouchet

Merge request reports