drf_yasg package¶
drf_yasg.codecs¶
-
drf_yasg.codecs.
VALIDATORS
= {'flex': <function _validate_flex at 0x7fbf3154cd90>, 'ssv': <function _validate_swagger_spec_validator at 0x7fbf3114e488>}¶
-
class
drf_yasg.codecs.
OpenAPICodecJson
(validators)[source]¶ Bases:
drf_yasg.codecs._OpenAPICodec
-
media_type
= 'application/json'¶
-
-
drf_yasg.codecs.
yaml_sane_dump
(data, binary)[source]¶ Dump the given data dictionary into a sane format:
- OrderedDicts are dumped as regular mappings instead of non-standard !!odict
- multi-line mapping style instead of json-like inline style
- list elements are indented into their parents
- YAML references/aliases are disabled
Parameters: - data (dict) – the data to be dumped
- binary (bool) – True to return a utf-8 encoded binary object, False to return a string
Returns: the serialized YAML
Return type: str,bytes
drf_yasg.errors¶
-
exception
drf_yasg.errors.
SwaggerValidationError
(msg, errors=None, spec=None, source_codec=None, *args)[source]¶ Bases:
drf_yasg.errors.SwaggerError
-
exception
drf_yasg.errors.
SwaggerGenerationError
[source]¶ Bases:
drf_yasg.errors.SwaggerError
drf_yasg.generators¶
-
class
drf_yasg.generators.
EndpointEnumerator
(patterns=None, urlconf=None, request=None)[source]¶ Bases:
rest_framework.schemas.generators.EndpointEnumerator
-
should_include_endpoint
(path, callback, app_name='', namespace='', url_name=None)[source]¶ Return True if the given endpoint should be included.
-
replace_version
(path, callback)[source]¶ If
request.version
is notNone
and callback usesURLPathVersioning
, this function replaces theversion
parameter in path with the actual version.Parameters: - path (str) – the templated path
- callback – the view callback
Return type: str
-
get_api_endpoints
(patterns=None, prefix='', app_name=None, namespace=None, ignored_endpoints=None)[source]¶ Return a list of all available API endpoints by inspecting the URL conf.
Copied entirely from super.
-
unescape
(s)[source]¶ Unescape all backslash escapes from s.
Parameters: s (str) – string with backslash escapes Return type: str
-
unescape_path
(path)[source]¶ Remove backslashe escapes from all path components outside {parameters}. This is needed because
simplify_regex
does not handle this correctly - note however that this implementation isNOTE: this might destructively affect some url regex patterns that contain metacharacters (e.g. w, d) outside path parameter groups; if you are in this category, God help you
Parameters: path (str) – path possibly containing Returns: the unescaped path Return type: str
-
-
class
drf_yasg.generators.
OpenAPISchemaGenerator
(info, version='', url=None, patterns=None, urlconf=None)[source]¶ Bases:
object
This class iterates over all registered API endpoints and returns an appropriate OpenAPI 2.0 compliant schema. Method implementations shamelessly stolen and adapted from rest-framework
SchemaGenerator
.Parameters: - info (Info) – information about the API
- version (str) – API version string; if omitted, info.default_version will be used
- url (str) –
API scheme, host and port; if
None
is passed andDEFAULT_API_URL
is not set, the url will be inferred from the request made against the schema view, so you should generally not need to set this parameter explicitly; if the empty string is passed, no host and scheme will be emittedIf url is not
None
or the empty string, it must be a scheme-absolute uri (i.e. starting with http:// or https://), and any path component is ignored;See also: documentation on base URL construction
- patterns – if given, only these patterns will be enumerated for inclusion in the API spec
- urlconf – if patterns is not given, use this urlconf to enumerate patterns; if not given, the default urlconf is used
-
endpoint_enumerator_class
¶ alias of
EndpointEnumerator
-
url
¶
-
get_schema
(request=None, public=False)[source]¶ Generate a
Swagger
object representing the API schema.Parameters: - request (Request) – the request used for filtering accesible endpoints and finding the spec URI
- public (bool) – if True, all endpoints are included regardless of access through request
Returns: the generated Swagger specification
Return type:
-
create_view
(callback, method, request=None)[source]¶ Create a view instance from a view callback as registered in urlpatterns.
Parameters: - callback (callable) – view callback registered in urlpatterns
- method (str) – HTTP method
- request (rest_framework.request.Request) – request to bind to the view
Returns: the view instance
-
get_endpoints
(request)[source]¶ Iterate over all the registered endpoints in the API and return a fake view with the right parameters.
Parameters: request (rest_framework.request.Request) – request to bind to the endpoint views Returns: {path: (view_class, list[(http_method, view_instance)]) Return type: dict
-
get_operation_keys
(subpath, method, view)[source]¶ Return a list of keys that should be used to group an operation within the specification.
/users/ ("users", "list"), ("users", "create") /users/{pk}/ ("users", "read"), ("users", "update"), ("users", "delete") /users/enabled/ ("users", "enabled") # custom viewset list action /users/{pk}/star/ ("users", "star") # custom viewset detail action /users/{pk}/groups/ ("users", "groups", "list"), ("users", "groups", "create") /users/{pk}/groups/{pk}/ ("users", "groups", "read"), ("users", "groups", "update")
Parameters: - subpath (str) – path to the operation with any common prefix/base path removed
- method (str) – HTTP method
- view – the view associated with the operation
Return type: tuple
-
determine_path_prefix
(paths)[source]¶ Given a list of all paths, return the common prefix which should be discounted when generating a schema structure.
This will be the longest common string that does not include that last component of the URL, or the last component before a path parameter.
For example:
/api/v1/users/ /api/v1/users/{pk}/
The path prefix is
/api/v1/
.Parameters: paths (list[str]) – list of paths Return type: str
-
get_paths
(endpoints, components, request, public)[source]¶ Generate the Swagger Paths for the API from the given endpoints.
Parameters: - endpoints (dict) – endpoints as returned by get_endpoints
- components (ReferenceResolver) – resolver/container for Swagger References
- request (Request) – the request made against the schema view; can be None
- public (bool) – if True, all endpoints are included regardless of access through request
Returns: the
Paths
object and the longest common path prefix, as a 2-tupleReturn type: tuple[openapi.Paths,str]
-
get_operation
(view, path, prefix, method, components, request)[source]¶ Get an
Operation
for the given API endpoint (path, method). This method delegates toget_operation()
of aViewInspector
determined according to settings and@swagger_auto_schema
overrides.Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- prefix (str) – common path prefix among all endpoints
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
Return type:
-
get_path_item
(path, view_cls, operations)[source]¶ Get a
PathItem
object that describes the parameters and operations related to a single path in the API.Parameters: - path (str) – the path
- view_cls (type) – the view that was bound to this path in urlpatterns
- operations (dict[str,openapi.Operation]) – operations defined on this path, keyed by lowercase HTTP method
Return type:
-
get_overrides
(view, method)[source]¶ Get overrides specified for a given operation.
Parameters: - view – the view associated with the operation
- method (str) – HTTP method
Returns: a dictionary containing any overrides set by
@swagger_auto_schema
Return type: dict
-
get_path_parameters
(path, view_cls)[source]¶ Return a list of Parameter instances corresponding to any templated path variables.
Parameters: - path (str) – templated request path
- view_cls (type) – the view class associated with the path
Returns: path parameters
Return type: list[openapi.Parameter]
drf_yasg.inspectors¶
-
drf_yasg.inspectors.
NotHandled
= <object object>¶ The most base type
-
class
drf_yasg.inspectors.
BaseInspector
(view, path, method, components, request)¶ Bases:
object
Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
-
probe_inspectors
(inspectors, method_name, obj, initkwargs=None, **kwargs)[source]¶ Probe a list of inspectors with a given object. The first inspector in the list to return a value that is not
NotHandled
wins.Parameters: - inspectors (list[type[BaseInspector]]) – list of inspectors to probe
- method_name (str) – name of the target method on the inspector
- obj – first argument to inspector method
- initkwargs (dict) – extra kwargs for instantiating inspector class
- kwargs – additional arguments to inspector method
Returns: the return value of the winning inspector, or
None
if no inspector handled the object
-
process_result
(result, method_name, obj, **kwargs)[source]¶ After an inspector handles an object (i.e. returns a value other than
NotHandled
), all inspectors that were probed get the chance to alter the result, in reverse order. The inspector that handled the object is the first to receive aprocess_result
call with the object it just returned.This behaviour is similar to the Django request/response middleware processing.
If this inspector has no post-processing to do, it should just
return result
(the default implementation).Parameters: - result – the return value of the winning inspector, or
None
if no inspector handled the object - method_name (str) – name of the method that was called on the inspector
- obj – first argument passed to inspector method
- kwargs – additional arguments passed to inspector method
Returns: - result – the return value of the winning inspector, or
-
class
drf_yasg.inspectors.
FilterInspector
(view, path, method, components, request)¶ Bases:
drf_yasg.inspectors.BaseInspector
Base inspector for filter backends.
Responsible for determining extra query parameters added by given filter backends.
Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
-
get_filter_parameters
(filter_backend)[source]¶ Get the filter parameters for a single filter backend instance.
Should return
NotHandled
if this inspector does not know how to handle the given filter_backend.Parameters: filter_backend (BaseFilterBackend) – the filter backend Return type: list[openapi.Parameter]
-
class
drf_yasg.inspectors.
PaginatorInspector
(view, path, method, components, request)¶ Bases:
drf_yasg.inspectors.BaseInspector
Base inspector for paginators.
Responisble for determining extra query parameters and response structure added by given paginators.
Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
-
get_paginated_response
(paginator, response_schema)[source]¶ Add appropriate paging fields to a response
Schema
.Should return
NotHandled
if this inspector does not know how to handle the given paginator.Parameters: - paginator (BasePagination) – the paginator
- response_schema (openapi.Schema) – the response schema that must be paged.
Return type:
-
get_paginator_parameters
(paginator)[source]¶ Get the pagination parameters for a single paginator instance.
Should return
NotHandled
if this inspector does not know how to handle the given paginator.Parameters: paginator (BasePagination) – the paginator Return type: list[openapi.Parameter]
-
class
drf_yasg.inspectors.
FieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.BaseInspector
Base inspector for serializers and serializer fields.
-
add_manual_fields
(serializer_or_field, schema)[source]¶ Set fields from the
swagger_schem_fields
attribute on the Meta class. This method is called only for serializers or fields that are converted intoopenapi.Schema
objects.Parameters: - serializer_or_field – serializer or field instance
- schema (openapi.Schema) – the schema object to be modified in-place
-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
probe_field_inspectors
(field, swagger_object_type, use_references, **kwargs)[source]¶ Helper method for recursively probing field_inspectors to handle a given field.
All arguments are the same as
field_to_swagger_object()
.Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
SerializerInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
-
get_request_parameters
(serializer, in_)[source]¶ Convert a DRF serializer into a list of
Parameter
s.Should return
NotHandled
if this inspector does not know how to handle the given serializer.Parameters: - serializer (serializers.BaseSerializer) – the
Serializer
instance - in (str) – the location of the parameters, one of the openapi.IN_* constants
Return type: list[openapi.Parameter]
- serializer (serializers.BaseSerializer) – the
-
get_schema
(serializer)[source]¶ Convert a DRF Serializer instance to an
openapi.Schema
.Should return
NotHandled
if this inspector does not know how to handle the given serializer.Parameters: serializer (serializers.BaseSerializer) – the Serializer
instanceReturn type: openapi.Schema
-
-
class
drf_yasg.inspectors.
ViewInspector
(view, path, method, components, request, overrides)¶ Bases:
drf_yasg.inspectors.BaseInspector
Inspector class responsible for providing
Operation
definitions given a view, path and method.Parameters: overrides (dict) – manual overrides as passed to @swagger_auto_schema
-
body_methods
= ('PUT', 'PATCH', 'POST', 'DELETE')¶
-
field_inspectors
= [<class 'drf_yasg.inspectors.field.CamelCaseJSONFilter'>, <class 'drf_yasg.inspectors.field.RecursiveFieldInspector'>, <class 'drf_yasg.inspectors.field.ReferencingSerializerInspector'>, <class 'drf_yasg.inspectors.field.ChoiceFieldInspector'>, <class 'drf_yasg.inspectors.field.FileFieldInspector'>, <class 'drf_yasg.inspectors.field.DictFieldInspector'>, <class 'drf_yasg.inspectors.field.HiddenFieldInspector'>, <class 'drf_yasg.inspectors.field.RelatedFieldInspector'>, <class 'drf_yasg.inspectors.field.SerializerMethodFieldInspector'>, <class 'drf_yasg.inspectors.field.SimpleFieldInspector'>, <class 'drf_yasg.inspectors.field.StringDefaultFieldInspector'>]¶
-
filter_inspectors
= [<class 'drf_yasg.inspectors.query.CoreAPICompatInspector'>]¶
-
get_filter_parameters
()[source]¶ Return the parameters added to the view by its filter backends.
Return type: list[openapi.Parameter]
-
get_operation
(operation_keys)[source]¶ Get an
Operation
for the given API endpoint (path, method). This includes query, body parameters and response schemas.Parameters: operation_keys (tuple[str]) – an array of keys describing the hierarchical layout of this view in the API; e.g. ('snippets', 'list')
,('snippets', 'retrieve')
, etc.Return type: openapi.Operation
-
get_paginated_response
(response_schema)[source]¶ Add appropriate paging fields to a response
Schema
.Parameters: response_schema (openapi.Schema) – the response schema that must be paged. Returns: the paginated response class:.Schema, or None
in case of an unknown pagination schemeReturn type: openapi.Schema
-
get_pagination_parameters
()[source]¶ Return the parameters added to the view by its paginator.
Return type: list[openapi.Parameter]
-
implicit_body_methods
= ('PUT', 'PATCH', 'POST')¶
-
paginator_inspectors
= [<class 'drf_yasg.inspectors.query.DjangoRestResponsePagination'>, <class 'drf_yasg.inspectors.query.CoreAPICompatInspector'>]¶
-
serializer_to_parameters
(serializer, in_)[source]¶ Convert a serializer to a possibly empty list of
Parameter
s.Parameters: - serializer (serializers.BaseSerializer) – the
Serializer
instance - in (str) – the location of the parameters, one of the openapi.IN_* constants
Return type: list[openapi.Parameter]
- serializer (serializers.BaseSerializer) – the
-
serializer_to_schema
(serializer)[source]¶ Convert a serializer to an OpenAPI
Schema
.Parameters: serializer (serializers.BaseSerializer) – the Serializer
instanceReturns: the converted Schema
, orNone
in case of an unknown serializerReturn type: openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
CoreAPICompatInspector
(view, path, method, components, request)¶ Bases:
drf_yasg.inspectors.PaginatorInspector
,drf_yasg.inspectors.FilterInspector
Converts
coreapi.Field
s toopenapi.Parameter
s for filters and paginators that implement aget_schema_fields
method.Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
-
coreapi_field_to_parameter
(field)[source]¶ Convert an instance of coreapi.Field to a swagger
Parameter
object.Parameters: field (coreapi.Field) – Return type: openapi.Parameter
-
get_filter_parameters
(filter_backend)[source]¶ Get the filter parameters for a single filter backend instance.
Should return
NotHandled
if this inspector does not know how to handle the given filter_backend.Parameters: filter_backend (BaseFilterBackend) – the filter backend Return type: list[openapi.Parameter]
-
get_paginator_parameters
(paginator)[source]¶ Get the pagination parameters for a single paginator instance.
Should return
NotHandled
if this inspector does not know how to handle the given paginator.Parameters: paginator (BasePagination) – the paginator Return type: list[openapi.Parameter]
-
class
drf_yasg.inspectors.
DjangoRestResponsePagination
(view, path, method, components, request)¶ Bases:
drf_yasg.inspectors.PaginatorInspector
Provides response schema pagination warpping for django-rest-framework’s LimitOffsetPagination, PageNumberPagination and CursorPagination
Parameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- components (openapi.ReferenceResolver) – referenceable components
- request (Request) – the request made against the schema view; can be None
-
get_paginated_response
(paginator, response_schema)[source]¶ Add appropriate paging fields to a response
Schema
.Should return
NotHandled
if this inspector does not know how to handle the given paginator.Parameters: - paginator (BasePagination) – the paginator
- response_schema (openapi.Schema) – the response schema that must be paged.
Return type:
-
class
drf_yasg.inspectors.
InlineSerializerInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.SerializerInspector
Provides serializer conversions using
FieldInspector.field_to_swagger_object()
.-
add_manual_parameters
(serializer, parameters)[source]¶ Add/replace parameters from the given list of automatically generated request parameters. This method is called only when the serializer is converted into a list of parameters for use in a form data request.
Parameters: - serializer – serializer instance
- parameters (list[openapi.Parameter]) – genereated parameters
Returns: modified parameters
Return type: list[openapi.Parameter]
-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
get_request_parameters
(serializer, in_)[source]¶ Convert a DRF serializer into a list of
Parameter
s.Should return
NotHandled
if this inspector does not know how to handle the given serializer.Parameters: - serializer (serializers.BaseSerializer) – the
Serializer
instance - in (str) – the location of the parameters, one of the openapi.IN_* constants
Return type: list[openapi.Parameter]
- serializer (serializers.BaseSerializer) – the
-
get_schema
(serializer)[source]¶ Convert a DRF Serializer instance to an
openapi.Schema
.Should return
NotHandled
if this inspector does not know how to handle the given serializer.Parameters: serializer (serializers.BaseSerializer) – the Serializer
instanceReturn type: openapi.Schema
-
use_definitions
= False¶
-
-
class
drf_yasg.inspectors.
RecursiveFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)
-
class
drf_yasg.inspectors.
ReferencingSerializerInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.InlineSerializerInspector
-
use_definitions
= True¶
-
-
class
drf_yasg.inspectors.
RelatedFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversions for
RelatedField
s.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
SimpleFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversions for fields which can be described using just
type
,format
,pattern
and min/max validators.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
FileFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversions for
FileField
s.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
ChoiceFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversions for
ChoiceField
andMultipleChoiceField
.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
DictFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversion for
DictField
.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
StringDefaultFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
For otherwise unhandled fields, return them as plain
TYPE_STRING
objects.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
CamelCaseJSONFilter
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Converts property names to camelCase if
CamelCaseJSONParser
orCamelCaseJSONRenderer
are used.-
process_result
(result, method_name, obj, **kwargs)[source]¶ After an inspector handles an object (i.e. returns a value other than
NotHandled
), all inspectors that were probed get the chance to alter the result, in reverse order. The inspector that handled the object is the first to receive aprocess_result
call with the object it just returned.This behaviour is similar to the Django request/response middleware processing.
If this inspector has no post-processing to do, it should just
return result
(the default implementation).Parameters: - result – the return value of the winning inspector, or
None
if no inspector handled the object - method_name (str) – name of the method that was called on the inspector
- obj – first argument passed to inspector method
- kwargs – additional arguments passed to inspector method
Returns: - result – the return value of the winning inspector, or
-
-
class
drf_yasg.inspectors.
HiddenFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Hide
HiddenField
.-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
SerializerMethodFieldInspector
(view, path, method, components, request, field_inspectors)¶ Bases:
drf_yasg.inspectors.FieldInspector
Provides conversion for SerializerMethodField, optionally using information from the swagger_serializer_method decorator.
-
field_to_swagger_object
(field, swagger_object_type, use_references, **kwargs)[source]¶ Convert a drf Serializer or Field instance into a Swagger object.
Should return
NotHandled
if this inspector does not know how to handle the given field.Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- use_references (bool) – if False, forces all objects to be declared inline instead of by referencing other components
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
-
-
class
drf_yasg.inspectors.
SwaggerAutoSchema
(view, path, method, components, request, overrides)¶ Bases:
drf_yasg.inspectors.ViewInspector
-
add_manual_parameters
(parameters)[source]¶ Add/replace parameters from the given list of automatically generated request parameters.
Parameters: parameters (list[openapi.Parameter]) – genereated parameters Returns: modified parameters Return type: list[openapi.Parameter]
-
get_default_response_serializer
()[source]¶ Return the default response serializer for this endpoint. This is derived from either the
request_body
override or the request serializer (get_view_serializer()
).Returns: response serializer, Schema
,SchemaRef
,None
-
get_default_responses
()[source]¶ Get the default responses determined for this view from the request serializer and request method.
Type: dict[str, openapi.Schema]
-
get_description
()[source]¶ Return an operation description determined as appropriate from the view’s method and class docstrings.
Returns: the operation description Return type: str
-
get_operation
(operation_keys)[source]¶ Get an
Operation
for the given API endpoint (path, method). This includes query, body parameters and response schemas.Parameters: operation_keys (tuple[str]) – an array of keys describing the hierarchical layout of this view in the API; e.g. ('snippets', 'list')
,('snippets', 'retrieve')
, etc.Return type: openapi.Operation
-
get_operation_id
(operation_keys)[source]¶ Return an unique ID for this operation. The ID must be unique across all
Operation
objects in the API.Parameters: operation_keys (tuple[str]) – an array of keys derived from the pathdescribing the hierarchical layout of this view in the API; e.g. ('snippets', 'list')
,('snippets', 'retrieve')
, etc.Return type: str
-
get_query_parameters
()[source]¶ Return the query parameters accepted by this view.
Return type: list[openapi.Parameter]
-
get_query_serializer
()[source]¶ Return the query serializer (used for parsing query parameters) for this endpoint.
Returns: the query serializer, or None
-
get_request_body_parameters
(consumes)[source]¶ Return the request body parameters for this view.
This is either:- a list with a single object Parameter with a
Schema
derived from the request serializer - a list of primitive Parameters parsed as form data
Parameters: consumes (list[str]) – a list of accepted MIME types as returned by get_consumes()
Returns: a (potentially empty) list of Parameter
s eitherin: body
orin: formData
Return type: list[openapi.Parameter] - a list with a single object Parameter with a
-
get_request_body_schema
(serializer)[source]¶ Return the
Schema
for a given request’s body data. Only applies to PUT, PATCH and POST requests.Parameters: serializer – the view’s request serializer as returned by get_request_serializer()
Return type: openapi.Schema
-
get_request_form_parameters
(serializer)[source]¶ Given a Serializer, return a list of
in: formData
Parameter
s.Parameters: serializer – the view’s request serializer as returned by get_request_serializer()
Return type: list[openapi.Parameter]
-
get_request_serializer
()[source]¶ Return the request serializer (used for parsing the request payload) for this endpoint.
Returns: the request serializer, or one of Schema
,SchemaRef
,None
-
get_response_schemas
(response_serializers)[source]¶ Return the
openapi.Response
objects calculated for this view.Parameters: response_serializers (dict) – response serializers as returned by get_response_serializers()
Returns: a dictionary of status code to Response
objectReturn type: dict[str, openapi.Response]
-
get_response_serializers
()[source]¶ Return the response codes that this view is expected to return, and the serializer for each response body. The return value should be a dict where the keys are possible status codes, and values are either strings,
Serializer
s,Schema
,SchemaRef
orResponse
objects. See@swagger_auto_schema
for more details.Returns: the response serializers Return type: dict
-
get_responses
()[source]¶ Get the possible responses for this view as a swagger
Responses
object.Returns: the documented responses Return type: openapi.Responses
-
get_security
()[source]¶ Return a list of security requirements for this operation.
Returning an empty list marks the endpoint as unauthenticated (i.e. removes all accepted authentication schemes). Returning
None
will inherit the top-level secuirty requirements.Returns: security requirements Return type: list[dict[str,list[str]]]
-
get_summary
()[source]¶ Return a summary description for this operation.
Returns: the summary Return type: str
Get a list of tags for this operation. Tags determine how operations relate with each other, and in the UI each tag will show as a group containing the operations that use it.
Parameters: operation_keys (tuple[str]) – an array of keys derived from the pathdescribing the hierarchical layout of this view in the API; e.g. ('snippets', 'list')
,('snippets', 'retrieve')
, etc.Return type: list[str]
-
get_view_serializer
()[source]¶ Return the serializer as defined by the view’s
get_serializer()
method.Returns: the view’s Serializer
-
is_deprecated
()[source]¶ Return
True
if this operation is to be marked as deprecated.Returns: deprecation status Return type: bool
-
make_body_parameter
(schema)[source]¶ Given a
Schema
object, create anin: body
Parameter
.Parameters: schema (openapi.Schema) – the request body schema Return type: openapi.Parameter
-
drf_yasg.middleware¶
drf_yasg.openapi¶
-
drf_yasg.openapi.
TYPE_OBJECT
= 'object'¶
-
drf_yasg.openapi.
TYPE_STRING
= 'string'¶
-
drf_yasg.openapi.
TYPE_NUMBER
= 'number'¶
-
drf_yasg.openapi.
TYPE_INTEGER
= 'integer'¶
-
drf_yasg.openapi.
TYPE_BOOLEAN
= 'boolean'¶
-
drf_yasg.openapi.
TYPE_ARRAY
= 'array'¶
-
drf_yasg.openapi.
TYPE_FILE
= 'file'¶
-
drf_yasg.openapi.
FORMAT_DATE
= 'date'¶
-
drf_yasg.openapi.
FORMAT_DATETIME
= 'date-time'¶
-
drf_yasg.openapi.
FORMAT_PASSWORD
= 'password'¶
-
drf_yasg.openapi.
FORMAT_BINARY
= 'binary'¶
-
drf_yasg.openapi.
FORMAT_BASE64
= 'bytes'¶
-
drf_yasg.openapi.
FORMAT_FLOAT
= 'float'¶
-
drf_yasg.openapi.
FORMAT_DOUBLE
= 'double'¶
-
drf_yasg.openapi.
FORMAT_INT32
= 'int32'¶
-
drf_yasg.openapi.
FORMAT_INT64
= 'int64'¶
-
drf_yasg.openapi.
FORMAT_EMAIL
= 'email'¶
-
drf_yasg.openapi.
FORMAT_IPV4
= 'ipv4'¶
-
drf_yasg.openapi.
FORMAT_IPV6
= 'ipv6'¶
-
drf_yasg.openapi.
FORMAT_URI
= 'uri'¶
-
drf_yasg.openapi.
FORMAT_UUID
= 'uuid'¶
-
drf_yasg.openapi.
FORMAT_SLUG
= 'slug'¶
-
drf_yasg.openapi.
IN_BODY
= 'body'¶
-
drf_yasg.openapi.
IN_PATH
= 'path'¶
-
drf_yasg.openapi.
IN_QUERY
= 'query'¶
-
drf_yasg.openapi.
IN_FORM
= 'formData'¶
-
drf_yasg.openapi.
IN_HEADER
= 'header'¶
-
drf_yasg.openapi.
SCHEMA_DEFINITIONS
= 'definitions'¶
-
drf_yasg.openapi.
make_swagger_name
(attribute_name)[source]¶ Convert a python variable name into a Swagger spec attribute name.
- In particular,
- if name starts with
x_
, returnx-{camelCase}
- if name is
ref
, return$ref
- else return the name converted to camelCase, with trailing underscores stripped
- if name starts with
Parameters: attribute_name (str) – python attribute name Returns: swagger name
-
class
drf_yasg.openapi.
SwaggerDict
(**attrs)[source]¶ Bases:
collections.OrderedDict
A particular type of OrderedDict, which maps all attribute accesses to dict lookups using
make_swagger_name()
. Attribute names starting with_
are set on the object as-is and are not included in the specification output.Used as a base class for all Swagger helper models.
-
class
drf_yasg.openapi.
Contact
(name=None, url=None, email=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Swagger Contact object
At least one of the following fields is required:
Parameters: - name (str) – contact name
- url (str) – contact url
- email (str) – contact e-mail
-
class
drf_yasg.openapi.
License
(name, url=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Swagger License object
Parameters: - name (str) – Required. License name
- url (str) – link to detailed license information
-
class
drf_yasg.openapi.
Info
(title, default_version, description=None, terms_of_service=None, contact=None, license=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Swagger Info object
Parameters: - title (str) – Required. API title.
- default_version (str) – Required. API version string (not to be confused with Swagger spec version)
- description (str) – API description; markdown supported
- terms_of_service (str) – API terms of service; should be a URL
- contact (Contact) – contact object
- license (License) – license object
-
class
drf_yasg.openapi.
Swagger
(info=None, _url=None, _prefix=None, _version=None, consumes=None, produces=None, security_definitions=None, security=None, paths=None, definitions=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Root Swagger object.
Parameters: - info (Info) – info object
- _url (str) – URL used for setting the API host and scheme
- _prefix (str) – api path prefix to use in setting basePath; this will be appended to the wsgi SCRIPT_NAME prefix or Django’s FORCE_SCRIPT_NAME if applicable
- _version (str) – version string to override Info
- security_definitions (dict[str,dict[str,str]]) – list of supported authentication mechanisms
- security (list[dict]) – authentication mechanisms accepted by default; can be overriden in Operation
- consumes (list[str]) – consumed MIME types; can be overriden in Operation
- produces (list[str]) – produced MIME types; can be overriden in Operation
- paths (Paths) – paths object
- definitions (dict[str,Schema]) – named models
-
classmethod
get_base_path
(script_prefix, api_prefix)[source]¶ Determine an appropriate value for
basePath
based on the SCRIPT_NAME and the api common prefix.Parameters: - script_prefix (str) – script prefix as defined by django
get_script_prefix
- api_prefix (str) – api common prefix
Returns: joined base path
- script_prefix (str) – script prefix as defined by django
-
class
drf_yasg.openapi.
Paths
(paths, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
A listing of all the paths in the API.
Parameters: paths (dict[str,PathItem]) –
-
class
drf_yasg.openapi.
PathItem
(get=None, put=None, post=None, delete=None, options=None, head=None, patch=None, parameters=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Information about a single path
Parameters: - get (Operation) – operation for GET
- put (Operation) – operation for PUT
- post (Operation) – operation for POST
- delete (Operation) – operation for DELETE
- options (Operation) – operation for OPTIONS
- head (Operation) – operation for HEAD
- patch (Operation) – operation for PATCH
- parameters (list[Parameter]) – parameters that apply to all operations
-
OPERATION_NAMES
= ['get', 'put', 'post', 'delete', 'options', 'head', 'patch']¶
-
operations
¶ A list of all standard Operations on this PathItem object. See
OPERATION_NAMES
.Returns: list of (method name, Operation) tuples Return type: list[tuple[str,Operation]]
-
class
drf_yasg.openapi.
Operation
(operation_id, responses, parameters=None, consumes=None, produces=None, summary=None, description=None, tags=None, security=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Information about an API operation (path + http method combination)
Parameters: - operation_id (str) – operation ID, should be unique across all operations
- responses (Responses) – responses returned
- parameters (list[Parameter]) – parameters accepted
- consumes (list[str]) – content types accepted
- produces (list[str]) – content types produced
- summary (str) – operation summary; should be < 120 characters
- description (str) – operation description; can be of any length and supports markdown
- tags (list[str]) – operation tags
- security (list[dict[str,list[str]]]) – list of security requirements
-
class
drf_yasg.openapi.
Items
(type=None, format=None, enum=None, pattern=None, items=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Used when defining an array
Parameter
to describe the array elements.Parameters: - type (str) – type of the array elements; must not be
object
- format (str) – value format, see OpenAPI spec
- enum (list) – restrict possible values
- pattern (str) – pattern if type is
string
- items (Items) – only valid if type is
array
- type (str) – type of the array elements; must not be
-
class
drf_yasg.openapi.
Parameter
(name, in_, description=None, required=None, schema=None, type=None, format=None, enum=None, pattern=None, items=None, default=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Describe parameters accepted by an
Operation
. Each parameter should be a unique combination of (name, in_).body
andform
parameters in the same operation are mutually exclusive.Parameters: - name (str) – parameter name
- in (str) – parameter location
- description (str) – parameter description
- required (bool) – whether the parameter is required for the operation
- schema (Schema,SchemaRef) – required if in_ is
body
- type (str) – parameter type; required if in_ is not
body
; must not beobject
- format (str) – value format, see OpenAPI spec
- enum (list) – restrict possible values
- pattern (str) – pattern if type is
string
- items (Items) – only valid if type is
array
- default – default value if the parameter is not provided; must conform to parameter type
-
class
drf_yasg.openapi.
Schema
(title=None, description=None, type=None, format=None, enum=None, pattern=None, properties=None, additional_properties=None, required=None, items=None, default=None, read_only=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes a complex object accepted as parameter or returned as a response.
Parameters: - title (str) – schema title
- description (str) – schema description
- type (str) – value type; required
- format (str) – value format, see OpenAPI spec
- enum (list) – restrict possible values
- pattern (str) – pattern if type is
string
- properties (dict[str,(Schema,SchemaRef)]) – object properties; required if type is
object
- additional_properties (bool,Schema,SchemaRef) – allow wildcard properties not listed in properties
- required (list[str]) – list of requried property names
- items (Schema,SchemaRef) – type of array items, only valid if type is
array
- default – only valid when insider another
Schema
’sproperties
; the default value of this property if it is not provided, must conform to the type of this Schema - read_only – only valid when insider another
Schema
’sproperties
; declares the property as read only - it must only be sent as part of responses, never in requests
-
OR_REF
= (<class 'drf_yasg.openapi.Schema'>, <class 'drf_yasg.openapi.SchemaRef'>)¶ useful for type-checking, e.g
isinstance(obj, openapi.Schema.OR_REF)
-
class
drf_yasg.openapi.
SchemaRef
(resolver, schema_name, ignore_unresolved=False)[source]¶ Bases:
drf_yasg.openapi._Ref
Adds a reference to a named Schema defined in the
#/definitions/
object.Parameters: - resolver (ReferenceResolver) – component resolver which must contain the definition
- schema_name (str) – schema name
- ignore_unresolved (bool) – allow the reference to be not defined in resolver
-
drf_yasg.openapi.
resolve_ref
(ref_or_obj, resolver)[source]¶ Resolve ref_or_obj if it is a reference type. Return it unchaged if not.
Parameters: - ref_or_obj (SwaggerDict,_Ref) –
- resolver – component resolver which must contain the referenced object
-
class
drf_yasg.openapi.
Responses
(responses, default=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes the expected responses of an
Operation
.Parameters:
-
class
drf_yasg.openapi.
Response
(description, schema=None, examples=None, **extra)[source]¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes the structure of an operation’s response.
Parameters:
-
class
drf_yasg.openapi.
ReferenceResolver
(*scopes)[source]¶ Bases:
object
A mapping type intended for storing objects pointed at by Swagger Refs. Provides support and checks for different refernce scopes, e.g. ‘definitions’.
For example:
> components = ReferenceResolver('definitions', 'parameters') > definitions = ReferenceResolver.with_scope('definitions') > definitions.set('Article', Schema(...)) > print(components) {'definitions': OrderedDict([('Article', Schema(...)]), 'parameters': OrderedDict()}
Parameters: scopes (str) – an enumeration of the valid scopes this resolver will contain -
with_scope
(scope)[source]¶ Return a view into this
ReferenceResolver
whose scope is defaulted and forced to scope.Parameters: scope (str) – target scope, must be in this resolver’s scopes Returns: the bound resolver Return type: ReferenceResolver
-
set
(name, obj, scope=None)[source]¶ Set an object in the given scope, raise an error if it already exists.
Parameters: - name (str) – reference name
- obj – referenced object
- scope (str) – reference scope
-
setdefault
(name, maker, scope=None)[source]¶ Set an object in the given scope only if it does not exist.
Parameters: - name (str) – reference name
- maker (callable) – object factory, called only if necessary
- scope (str) – reference scope
-
get
(name, scope=None)[source]¶ Get an object from the given scope, raise an error if it does not exist.
Parameters: - name (str) – reference name
- scope (str) – reference scope
Returns: the object
-
getdefault
(name, default=None, scope=None)[source]¶ Get an object from the given scope or a default value if it does not exist.
Parameters: - name (str) – reference name
- default – the default value
- scope (str) – reference scope
Returns: the object or default
-
has
(name, scope=None)[source]¶ Check if an object exists in the given scope.
Parameters: - name (str) – reference name
- scope (str) – reference scope
Returns: True if the object exists
Return type: bool
-
scopes
¶
-
drf_yasg.renderers¶
-
class
drf_yasg.renderers.
OpenAPIRenderer
[source]¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a JSON document with the
application/openapi+json
specific mime type.-
media_type
= 'application/openapi+json'¶
-
format
= 'openapi'¶
-
codec_class
¶ alias of
drf_yasg.codecs.OpenAPICodecJson
-
-
class
drf_yasg.renderers.
SwaggerJSONRenderer
[source]¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a JSON document with the generic
application/json
mime type.-
media_type
= 'application/json'¶
-
format
= '.json'¶
-
codec_class
¶ alias of
drf_yasg.codecs.OpenAPICodecJson
-
-
class
drf_yasg.renderers.
SwaggerYAMLRenderer
[source]¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a YAML document.
-
media_type
= 'application/yaml'¶
-
format
= '.yaml'¶
-
codec_class
¶ alias of
drf_yasg.codecs.OpenAPICodecYaml
-
-
class
drf_yasg.renderers.
SwaggerUIRenderer
[source]¶ Bases:
drf_yasg.renderers._UIRenderer
Renders a swagger-ui web interface for schema browisng.
-
template
= 'drf-yasg/swagger-ui.html'¶
-
format
= 'swagger'¶
-
-
class
drf_yasg.renderers.
ReDocRenderer
[source]¶ Bases:
drf_yasg.renderers._UIRenderer
Renders a ReDoc web interface for schema browisng.
-
template
= 'drf-yasg/redoc.html'¶
-
format
= 'redoc'¶
-
-
class
drf_yasg.renderers.
ReDocOldRenderer
[source]¶ Bases:
drf_yasg.renderers.ReDocRenderer
Renders a ReDoc 1.x.x web interface for schema browisng.
-
template
= 'drf-yasg/redoc-old.html'¶
-
drf_yasg.utils¶
-
class
drf_yasg.utils.
no_body
[source]¶ Bases:
object
Used as a sentinel value to forcibly remove the body of a request via
swagger_auto_schema()
.
-
class
drf_yasg.utils.
unset
[source]¶ Bases:
object
Used as a sentinel value for function parameters not set by the caller where
None
would be a valid value.
-
drf_yasg.utils.
swagger_auto_schema
(method=None, methods=None, auto_schema=<class 'drf_yasg.utils.unset'>, request_body=None, query_serializer=None, manual_parameters=None, operation_id=None, operation_description=None, operation_summary=None, security=None, deprecated=None, responses=None, field_inspectors=None, filter_inspectors=None, paginator_inspectors=None, **extra_overrides)[source]¶ Decorate a view method to customize the
Operation
object generated from it.method and methods are mutually exclusive and must only be present when decorating a view method that accepts more than one HTTP request method.
The auto_schema and operation_description arguments take precendence over view- or method-level values.
Parameters: - method (str) – for multi-method views, the http method the options should apply to
- methods (list[str]) – for multi-method views, the http methods the options should apply to
- auto_schema (inspectors.SwaggerAutoSchema) – custom class to use for generating the Operation object;
this overrides both the class-level
swagger_schema
attribute and theDEFAULT_AUTO_SCHEMA_CLASS
setting, and can be set toNone
to prevent this operation from being generated - request_body (Schema,SchemaRef,Serializer) –
custom request body, or
no_body
. The value given here will be used as theschema
property of aParameter
within: 'body'
.A Schema or SchemaRef is not valid if this request consumes form-data, because
form
andbody
parameters are mutually exclusive in anOperation
. If you need to set customform
parameters, you can use the manual_parameters argument.If a
Serializer
class or instance is given, it will be automatically converted into aSchema
used as abody
Parameter
, or into a list ofform
Parameter
s, as appropriate. - query_serializer (Serializer) –
if you use a
Serializer
to parse query parameters, you can pass it here and haveParameter
objects be generated automatically from it.If any
Field
on the serializer cannot be represented as aquery
Parameter
(e.g. nested Serializers, file fields, …), the schema generation will fail with an error.Schema generation will also fail if the name of any Field on the query_serializer conflicts with parameters generated by
filter_backends
orpaginator
. - manual_parameters (list[Parameter]) –
a list of manual parameters to override the automatically generated ones
Parameter
s are identified by their (name
,in
) combination, and any parameters given here will fully override automatically generated parameters if they collide.It is an error to supply
form
parameters when the request does not consume form-data. - operation_id (str) – operation ID override; the operation ID must be unique accross the whole API
- operation_description (str) – operation description override
- operation_summary (str) – operation summary string
- security (list[dict]) – security requirements override; used to specify which authetication mechanism
is requried to call this API; an empty list marks the endpoint as unauthenticated (i.e. removes all accepted
authentication schemes), and
None
will inherit the top-level secuirty requirements - deprecated (bool) – deprecation status for operation
- responses (dict[str,(Schema,SchemaRef,Response,str,Serializer)]) –
a dict of documented manual responses keyed on response status code. If no success (
2xx
) response is given, one will automatically be generated from the request body and http method. If any2xx
response is given the automatic response is suppressed.- if a plain string is given as value, a
Response
with no body and that string as its description will be generated - if
None
is given as a value, the response is ignored; this is mainly useful for disabling default 2xx responses, i.e.responses={200: None, 302: 'something'}
- if a
Schema
,SchemaRef
is given, aResponse
with the schema as its body and an empty description will be generated - a
Serializer
class or instance will be converted into aSchema
and treated as above - a
Response
object will be used as-is; however if itsschema
attribute is aSerializer
, it will automatically be converted into aSchema
- if a plain string is given as value, a
- field_inspectors (list[FieldInspector]) – extra serializer and field inspectors; these will be tried
before
ViewInspector.field_inspectors
on theinspectors.SwaggerAutoSchema
instance - filter_inspectors (list[FilterInspector]) – extra filter inspectors; these will be tried before
ViewInspector.filter_inspectors
on theinspectors.SwaggerAutoSchema
instance - paginator_inspectors (list[PaginatorInspector]) – extra paginator inspectors; these will be tried before
ViewInspector.paginator_inspectors
on theinspectors.SwaggerAutoSchema
instance - extra_overrides – extra values that will be saved into the
overrides
dict; these values will be available in the handlinginspectors.SwaggerAutoSchema
instance viaself.overrides
-
drf_yasg.utils.
swagger_serializer_method
(serializer_or_field)[source]¶ Decorates the method of a serializers.SerializerMethodField to hint as to how Swagger should be generated for this field.
Parameters: serializer_or_field – Serializer
/Field
class or instanceReturns:
-
drf_yasg.utils.
is_list_view
(path, method, view)[source]¶ Check if the given path/method appears to represent a list view (as opposed to a detail/instance view).
Parameters: - path (str) – view path
- method (str) – http method
- view (APIView) – target view
Return type: bool
-
drf_yasg.utils.
param_list_to_odict
(parameters)[source]¶ Transform a list of
Parameter
objects into anOrderedDict
keyed on the(name, in_)
tuple of each parameter.Raises an
AssertionError
if parameters contains duplicate parameters (by their name + in combination).Parameters: parameters (list[Parameter]) – the list of parameters Returns: parameters keyed by (name, in_)
Return type: dict[tuple(str,str),Parameter]
-
drf_yasg.utils.
merge_params
(parameters, overrides)[source]¶ Merge overrides into parameters. This is the same as appending overrides to parameters, but any element of parameters whose
(name, in_)
tuple collides with an element in overrides is replaced by it.Raises an
AssertionError
if either list contains duplicate parameters.Parameters: Returns: merged list
Return type: list[Parameter]
-
drf_yasg.utils.
filter_none
(obj)[source]¶ Remove
None
values from tuples, lists or dictionaries. Return other objects as-is.Parameters: obj – Returns: collection with None
values removed
-
drf_yasg.utils.
force_serializer_instance
(serializer)[source]¶ Force serializer into a
Serializer
instance. If it is not aSerializer
class or instance, raises an assertion error.Parameters: serializer – serializer class or instance Returns: serializer instance Return type: serializers.BaseSerializer
-
drf_yasg.utils.
get_serializer_class
(serializer)[source]¶ Given a
Serializer
class or intance, return theSerializer
class. If serializer is not aSerializer
class or instance, raises an assertion error.Parameters: serializer – serializer class or instance, or None
Returns: serializer class Return type: type[serializers.BaseSerializer]
-
drf_yasg.utils.
get_consumes
(parser_classes)[source]¶ Extract
consumes
MIME types from a list of parser classes.Parameters: parser_classes (list) – parser classes Returns: MIME types for consumes
Return type: list[str]
-
drf_yasg.utils.
get_produces
(renderer_classes)[source]¶ Extract
produces
MIME types from a list of renderer classes.Parameters: renderer_classes (list) – renderer classes Returns: MIME types for produces
Return type: list[str]
-
drf_yasg.utils.
decimal_as_float
(field)[source]¶ Returns true if
field
is a django-rest-framework DecimalField and itscoerce_to_string
attribute or theCOERCE_DECIMAL_TO_STRING
setting is set toFalse
.Return type: bool
-
drf_yasg.utils.
get_serializer_ref_name
(serializer)[source]¶ Get serializer’s ref_name (or None for ModelSerializer if it is named ‘NestedSerializer’)
Parameters: serializer – Serializer instance Returns: Serializer’s ref_name
orNone
for inline serializerReturn type: str
drf_yasg.views¶
-
drf_yasg.views.
deferred_never_cache
(view_func)[source]¶ Decorator that adds headers to a response so that it will never be cached.
-
drf_yasg.views.
get_schema_view
(info=None, url=None, patterns=None, urlconf=None, public=False, validators=None, generator_class=None, authentication_classes=None, permission_classes=None)[source]¶ Create a SchemaView class with default renderers and generators.
Parameters: - info (Info) – information about the API; if omitted, defaults to DEFAULT_INFO
- url (str) – same as
OpenAPISchemaGenerator
- patterns – same as
OpenAPISchemaGenerator
- urlconf – same as
OpenAPISchemaGenerator
- public (bool) – if False, includes only the endpoints that are accesible by the user viewing the schema
- validators (list) – a list of validator names to apply; allowed values are
flex
,ssv
- generator_class (type) – schema generator class to use; should be a subclass of
OpenAPISchemaGenerator
- authentication_classes (tuple) – authentication classes for the schema view itself
- permission_classes (tuple) – permission classes for the schema view itself
Returns: SchemaView class
Return type: type[SchemaView]
-
class
drf_yasg.views.
SchemaView
(**kwargs)¶ Bases:
rest_framework.views.APIView
Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.
-
classmethod
apply_cache
(view, cache_timeout, cache_kwargs)¶ Override this method to customize how caching is applied to the view.
Arguments described in
as_cached_view()
.
-
classmethod
as_cached_view
(cache_timeout=0, cache_kwargs=None, **initkwargs)¶ Calls .as_view() and wraps the result in a cache_page decorator. See https://docs.djangoproject.com/en/1.11/topics/cache/
Parameters: - cache_timeout (int) – same as cache_page; set to 0 for no cache
- cache_kwargs (dict) – dictionary of kwargs to be passed to cache_page
- initkwargs – kwargs for .as_view()
Returns: a view instance
-
authentication_classes
= [<class 'rest_framework.authentication.SessionAuthentication'>, <class 'rest_framework.authentication.BasicAuthentication'>]¶
-
generator_class
¶
-
get
(request, version='', format=None)¶
-
permission_classes
= [<class 'rest_framework.permissions.AllowAny'>]¶
-
public
= False¶
-
renderer_classes
= (<class 'drf_yasg.renderers.SwaggerYAMLRenderer'>, <class 'drf_yasg.renderers.SwaggerJSONRenderer'>, <class 'drf_yasg.renderers.OpenAPIRenderer'>)¶
-
schema
= None¶
-
classmethod
with_ui
(renderer='swagger', cache_timeout=0, cache_kwargs=None)¶ Instantiate this view with a Web UI renderer, optionally wrapped with cache_page. See https://docs.djangoproject.com/en/1.11/topics/cache/.
Parameters: - renderer (str) – UI renderer; allowed values are
swagger
,redoc
- cache_timeout (int) – same as cache_page; set to 0 for no cache
- cache_kwargs (dict) – dictionary of kwargs to be passed to cache_page
Returns: a view instance
- renderer (str) – UI renderer; allowed values are
-
classmethod
without_ui
(cache_timeout=0, cache_kwargs=None)¶ Instantiate this view with just JSON and YAML renderers, optionally wrapped with cache_page. See https://docs.djangoproject.com/en/1.11/topics/cache/.
Parameters: - cache_timeout (int) – same as cache_page; set to 0 for no cache
- cache_kwargs (dict) – dictionary of kwargs to be passed to cache_page
Returns: a view instance
-
classmethod