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.
Note
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.
Decorators¶
@swagger_auto_schema
is largely equivalent to@extend_schema
.operation_description
argument is calleddescription
operation_summary
argument is calledsummary
manual_parameters
andquery_serializer
arguments are merged into a singleparameters
argumentsecurity
argument is calledauth
request_body
arguments is calledrequest
Use
None
instead ofdrf_yasg.utils.no_body
method
argument doesn’t exist, usemethods
instead (also supported by drf-yasg)auto_schema
has no equivalent.extra_overrides
has no equivalent.field_inspectors
has no equivalent.filter_inspectors
has no equivalent.paginator_inspectors
has no equivalent.Additional arguments are also available:
exclude
,operation
,versions
,examples
.
@swagger_serializer_method
is equivalent to@extend_schema_field
.component_name
can be provided to break the field out as a separate component.
@extend_schema_serializer
is available for overriding behavior of serializers.Instead of using
@method_decorator
, use@extend_schema_view
.Instead of using
swagger_schema_field
, use@extend_schema_field
or@extend_schema_serializer
.
Helper Classes¶
Parameter
is roughly equivalent toOpenApiParameter
.in_
argument is calledlocation
.schema
argument should be passed astype
.format
argument is merged intotype
argument by usingOpenApiTypes
.setting the
many
argument toTrue
causes the argument to take an array of values, and generates a schema similar to using the drf_yasgItems
class on theitems
property. The type of the items in the array are defined by thetype
argument.
Response
is largely identical toOpenApiResponse
.schema
argument is calledresponse
Order of arguments differs, so use keyword arguments.
OpenApiExample
is available for providingexamples
to@extend_schema
.Schema
is not required and can be eliminated. Use a plaindict
instead.
Types & Formats¶
In place of separate drf_yasg.openapi.TYPE_*
and drf_yasg.openapi.FORMAT_*
constants, drf-spectacular
provides the OpenApiTypes
enum:
TYPE_BOOLEAN
is calledBOOL
, but you can usebool
.TYPE_INTEGER
is calledINT
, but you can useint
.TYPE_INTEGER
withFORMAT_INT32
is calledINT32
TYPE_INTEGER
withFORMAT_INT64
is calledINT64
TYPE_NUMBER
is calledNUMBER
TYPE_NUMBER
withFORMAT_FLOAT
is calledFLOAT
, but you can usefloat
.TYPE_NUMBER
withFORMAT_DOUBLE
is calledDOUBLE
(orDECIMAL
, but you can useDecimal
)TYPE_OBJECT
is calledOBJECT
, but you can usedict
.TYPE_STRING
is calledSTR
, but you can usestr
.TYPE_STRING
withFORMAT_BASE64
is calledBYTE
(which is base64 encoded).TYPE_STRING
withFORMAT_BINARY
is calledBINARY
, but you can usebytes
.TYPE_STRING
withFORMAT_DATETIME
is calledDATETIME
, but you can usedatetime.datetime
.TYPE_STRING
withFORMAT_DATE
is calledDATE
, but you can usedatetime.date
.TYPE_STRING
withFORMAT_EMAIL
is calledEMAIL
TYPE_STRING
withFORMAT_IPV4
is calledIP4
, but you can useipaddress.IPv4Address
.TYPE_STRING
withFORMAT_IPV6
is calledIP6
, but you can useipaddress.IPv6Address
.TYPE_STRING
withFORMAT_PASSWORD
is calledPASSWORD
TYPE_STRING
withFORMAT_URI
is calledURI
TYPE_STRING
withFORMAT_UUID
is calledUUID
, but you can useuuid.UUID
.TYPE_STRING
withFORMAT_SLUG
has no direct equivalent. UseSTR
orstr
instead.TYPE_ARRAY
is handled by providingOpenApiParameter
withmany=True
as a parameter. There is no need to set theitems
property on the parameter - the presence ofmany=True
turns the parameter into an array parameter.The following additional types are also available:
ANY
for which you can usetyping.Any
.DURATION
for which you can usedatetime.timedelta
.TIME
for which you can usedatetime.time
.
Parameter Location¶
drf_yasg.openapi.IN_*
constants are roughly equivalent to constants defined on the
OpenApiParameter
class:
Docstring Parsing¶
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
summary
and description
arguments of @extend_schema
instead.
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,
use the summary
and description
arguments of @extend_schema
instead:
# 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):
...
Authentication¶
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.
Compatibility¶
For compatibility, the following features of drf-yasg have been implemented:
ref_name
onSerializer
Meta
classes is supported (excluding inlining withref_name=None
)See drf-yasg’s documentation for further details.
The equivalent in
drf-spectacular
is@extend_schema_serializer(component_name="...")
swagger_fake_view
is available as attribute on views to signal schema generation