Package overview

drf_spectacular.utils

class drf_spectacular.utils.OpenApiParameter(name, type=<class 'str'>, location='query', required=False, description='', enum=None, deprecated=False)

Bases: drf_spectacular.utils.OpenApiSchemaBase

COOKIE = 'cookie'
HEADER = 'header'
PATH = 'path'
QUERY = 'query'
class drf_spectacular.utils.OpenApiSchemaBase

Bases: object

class drf_spectacular.utils.PolymorphicProxySerializer(component_name, serializers, resource_type_field_name)

Bases: object

This class is to be used with @extend_schema to signal a request/response might be polymorphic (accepts/returns data possibly from different serializers)

Beware that this is not a real serializer and therefore is not derived from serializers.Serializer. It cannot be used in views as serializer_class or as field in a actual serializer. You likely want to handle this in the view method.

Also make sure that each sub-serializer has a field named after the value of resource_type_field (discriminator field) for the the mapping and parity with with the generated schema.

drf_spectacular.utils.extend_schema(operation_id=None, parameters=None, request=None, responses=None, auth=None, description=None, deprecated=None, tags=None, exclude=False, operation=None, methods=None)

decorator for the “view” kind. partially or completely overrides what would be generated by drf-spectacular.

Parameters

  • operation_id – replaces the auto-generated operation_id. make sure there are no naming collisions.

  • parameters – list of additional or replacement parameters added to the auto-discovered fields.

  • responses –

    replaces the discovered Serializer. Takes a variety of inputs that can be used individually or combined

    • Serializer class

    • Serializer instance (e.g. Serializer(many=True) for listings)

    • dict with status codes as keys and Serializers as values.

    • PolymorphicProxySerializer for signaling that the operation may yield data from different serializers depending on the circumstances.

  • request – replaces the discovered Serializer.

  • auth –

  • description – replaces discovered doc strings

  • deprecated – mark operation as deprecated

  • tags – override default list of tags

  • exclude – set True to exclude operation from schema

  • operation – manually override what auto-discovery would generate. you must provide a OpenAPI3-compliant dictionary that gets directly translated to YAML.

  • methods – scope extend_schema to specific methods. matches all by default.

Returns

drf_spectacular.utils.extend_schema_field(field)

Decorator for the “field” kind. Can be used with SerializerMethodField (annotate the actual method) or with custom serializers.Field implementations.

If your custom serializer field base class is already the desired type, decoration is not necessary. To override the discovered base class type, you can decorate your custom field class.

Always takes precedence over other mechanisms (e.g. type hints, auto-discovery).

Parameters

field – accepts a Serializer or OpenApiTypes

drf_spectacular.types

class drf_spectacular.types.OpenApiTypes

Basic types known to the OpenApi specification or at least common format extension of it.

  • Use BYTE for base64 encoded data wrapped in a string

  • Use BINARY for raw binary data

  • Use OBJECT for arbitrary free-form object (usually a dict)

BINARY = 5
BOOL = 2
BYTE = 4
DATE = 14
DATETIME = 13
DECIMAL = 12
EMAIL = 15
FLOAT = 1
HOSTNAME = 11
INT = 6
IP4 = 9
IP6 = 10
NONE = 17
OBJECT = 16
STR = 3
URI = 8
UUID = 7

drf_spectacular.views

class drf_spectacular.views.SpectacularAPIView(**kwargs)

Bases: rest_framework.views.APIView

OpenApi3 schema for this API. Format can be selected via content negotiation.

  • YAML: application/vnd.oai.openapi

  • JSON: application/vnd.oai.openapi+json

get(request)
permission_classes = [<class 'rest_framework.permissions.AllowAny'>]
renderer_classes = [<class 'drf_spectacular.renderers.NoAliasOpenAPIRenderer'>, <class 'rest_framework.renderers.JSONOpenAPIRenderer'>]
class drf_spectacular.views.SpectacularJSONAPIView(**kwargs)

Bases: drf_spectacular.views.SpectacularAPIView

renderer_classes = [<class 'rest_framework.renderers.JSONOpenAPIRenderer'>]
class drf_spectacular.views.SpectacularYAMLAPIView(**kwargs)

Bases: drf_spectacular.views.SpectacularAPIView

renderer_classes = [<class 'drf_spectacular.renderers.NoAliasOpenAPIRenderer'>]

drf_spectacular.openapi

class drf_spectacular.openapi.AutoSchema

Bases: rest_framework.schemas.inspectors.ViewInspector

get_auth(path, method)

Obtains authentication classes and permissions from view. If authentication is known, resolve security requirement for endpoint and security definition for the component section. For custom authentication subclass OpenApiAuthenticationExtension.

get_description(path, method)

override this for custom behaviour

get_operation(path, method, registry: drf_spectacular.plumbing.ComponentRegistry)
get_operation_id(path, method)

override this for custom behaviour

get_override_parameters(path, method)

override this for custom behaviour

get_request_serializer(path, method)

override this for custom behaviour

get_response_serializers(path, method)

override this for custom behaviour

get_tags(path, method) → List[str]

override this for custom behaviour

is_deprecated(path, method)

override this for custom behaviour

map_parsers(path, method)
map_renderers(path, method)
method_mapping = {'delete': 'destroy', 'get': 'retrieve', 'patch': 'partial_update', 'post': 'create', 'put': 'update'}
resolve_serializer(method, serializer) → drf_spectacular.plumbing.ResolvedComponent
class drf_spectacular.openapi.SchemaGenerator(*args, **kwargs)

Bases: rest_framework.schemas.generators.BaseSchemaGenerator

create_view(callback, method, request=None)

customized create_view which is called when all routes are traversed. part of this is instatiating views with default params. in case of custom routes (@action) the custom AutoSchema is injected properly through ‘initkwargs’ on view. However, when decorating plain views like retrieve, this initialization logic is not running. Therefore forcefully set the schema if @extend_schema decorator was used.

get_endpoints(request)

sorted endpoints by operation

get_schema(request=None, public=False)

Generate a OpenAPI schema.

parse(request=None)

Iterate endpoints generating per method path operations.