OpenAPI3 proposal for enhancements/fixes

[ghost]

I created an issue for this at #7088

This is quite a lot of stuff, some of it would be optional and can be rolled back. The schema generation already works very well on our products APIs (apart from a few rough edges).

Feedback is very welcome. Would love to see this merged.

Features

• abstraction of serializers into components section (better support for openapi-generator)
• @extend_schema decorator enables a multitude of customizations, e.g.
  • @extend_schema works on ViewSet methods, APIView methods, and function-based views
  • additional manual query parameters
  • request serializer override
  • response serializers override
  • response status code override (with serializer)
  • manual polymorphic responses (via multiple serializers)
• schema tags for operations (+ override option) (very useful in Swagger UI)
• authentication methods in schema (default implementations for DRF included schemes)
• method for providing custom authentication schemes
• seperate component versions for PATCH serializers (no required fields)
• support for django-polymorphic/rest_polymorphic (automatic polymorphic responses for PolymorphicSerializers)
• SerializerMethodField() output type via type hinting
• description extraction from doc strings (still a bit rough)
• revised operation_id naming (preventing operation id duplication)
• sane fallbacks where there are no serializers available (free-form objects)
• some more minor schema improvements
• generateschema file output and more parameters for generateschema
• generateschema bugfix yaml aliases output in schema

Todos

• fixing the remaining tests
• adding new tests
• documentation for usage in general and usage of the @extend_schema decorator

[carltongibson]

Hi @tfranzel-cashlink. Interesting thanks.

There’s too much going on at once here, so we’ll need to break this up. Then there’s some things that aren’t quite the way I’d have them, for instance the serializer mapping should work on a concrete serializer rather than taking the request method. But I like the ideas.

Can you perhaps begin with a PR for the component registry? I think that’s the clearest.

I’ll have some time to look over this properly over the holidays, so if we can break it up we should be able to get the key parts in.

[carltongibson]

Superseded by sub PRs and #7124 which will provide component support.