From drf-yasg to OpenAPI 3
drf-yasg is an excellent library and the most popular choice for generating OpenAPI 2.0 (formerly known as Swagger
2.0) schemas with Django REST Framework. Unfortunately, it currently does not provide support for OpenAPI 3.x.
drf-spectacular requires some modifications, the complexity of which depends on what
features are being used.
In contrast to drf-yasg, we don’t package Redoc & Swagger UI but serve them via hyperliked CDNs instead. If you want or need to serve those files yourself, you can do that with the optional drf-spectacular-sidecar. See installation instructions for further details.
operation_descriptionargument is called
operation_summaryargument is called
query_serializerarguments are merged into a single
securityargument is called
request_bodyarguments is called
methodargument doesn’t exist, use
methodsinstead (also supported by
auto_schemahas no equivalent.
extra_overrideshas no equivalent.
field_inspectorshas no equivalent.
filter_inspectorshas no equivalent.
paginator_inspectorshas no equivalent.
Additional arguments are also available:
component_namecan be provided to break the field out as a separate component.
@extend_schema_serializeris available for overriding behavior of serializers.
in_argument is called
schemaargument should be passed as
formatargument is merged into
typeargument by using
schemaargument is called
Order of arguments differs, so use keyword arguments.
Types & Formats
In place of separate
TYPE_ARRAYhas no direct equivalent.
The following additional types are also available:
drf_yasg.openapi.IN_* constants are roughtly equivalent to constants defined on the
drf-yasg has some special handling for docstrings that is not supported by
It attempts to split the first line from the rest of the docstring to use as the operation summary, and the remainder
is used as the operation description.
drf-spectacular uses the entire docstring as the description. Use the
description arguments of
Optionally, the docstring can still be used to populate the operation description.
# Supported by drf-yasg: class UserViewSet(ViewSet): def list(self, request): """ List all the users. Return a list of all usernames in the system. """ ... # Updated for drf-spectacular using decorator for description: class UserViewSet(ViewSet): @extend_schema( summary="List all the users.", description="Return a list of all usernames in the system.", ) def list(self, request): ... # Updated for drf-spectacular using docstring for description: class UserViewSet(ViewSet): @extend_schema(summary="List all the users.") def list(self, request): """Return a list of all usernames in the system.""" ...
# Supported by drf-yasg: class UserViewSet(ViewSet): """ list: List all the users. Return a list of all usernames in the system. retrieve: Retrieve user Get details of a specific user """ ... # Updated for drf-spectacular using decorator for description: @extend_schema_view( list=extend_schema( summary="List all the users.", description="Return a list of all usernames in the system.", ), retrieve=extend_schema( summary="Retrieve user", description="Get details of a specific user", ), ) class UserViewSet(ViewSet): ...
drf-yasg it was necessary to manually describe authentication schemes.
drf-spectacular there is support for auto-generating the security definitions for a number of authentication
classes built in to DRF as well as other popular third-party packages.
OpenApiAuthenticationExtension is available to help tie in custom
authentication clasees – see the customization guide.
For compatibility, the following features of
drf-yasg have been implemented:
Metaclasses is supported (excluding inlining with
See drf-yasg’s documentation for further details.
The equivalent in
swagger_fake_viewis available as attribute on views to signal schema generation