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.
@swagger_auto_schemais largely equivalent to
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:
@swagger_serializer_methodis equivalent to
component_namecan be provided to break the field out as a separate component.
@extend_schema_serializeris available for overriding behavior of serializers.
Instead of using
Instead of using
Parameteris roughly equivalent to
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
Responseis largely identical to
schemaargument is called
Order of arguments differs, so use keyword arguments.
OpenApiExampleis available for providing
Schemais not required and can be eliminated. Use a plain
Types & Formats
In place of separate
BOOL, but you can use
INT, but you can use
FLOAT, but you can use
DECIMAL, but you can use
OBJECT, but you can use
STR, but you can use
BYTE(which is base64 encoded).
BINARY, but you can use
DATETIME, but you can use
DATE, but you can use
IP4, but you can use
IP6, but you can use
UUID, but you can use
FORMAT_SLUGhas no direct equivalent. Use
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:
ANYfor which you can use
DURATIONfor which you can use
TIMEfor which you can use
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 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.""" ...
In addition, drf-yasg also supports named sections, but these are not supported by drf-spectacular. Again,
description arguments of
# 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