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. Migration from drf-yasg to 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 hyperlinked CDNs instead. If you want or need to serve those files yourself, you can do that with the optional drf-spectacular-sidecar package. 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 drf-yasg)
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
Truecauses the argument to take an array of values, and generates a schema similar to using the drf_yasg
Itemsclass on the
itemsproperty. The type of the items in the array are defined by the
schemaargument is called
Order of arguments differs, so use keyword arguments.
Types & Formats
In place of separate
TYPE_ARRAYis handled by providing
many=Trueas a parameter. There is no need to set the
itemsproperty on the parameter - the presence of
many=Trueturns the parameter into an array parameter.
The following additional types are also available:
drf_yasg.openapi.IN_* constants are roughly equivalent to constants defined on the
drf-yasg has some special handling for docstrings that is not supported by drf-spectacular.
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): ...
In drf-yasg it was necessary to manually describe authentication schemes.
In 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