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
classSerializer
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 customserializers.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
orOpenApiTypes
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
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.
-