drf_yasg package¶
drf_yasg.app_settings¶
drf_yasg.codecs¶
-
class
drf_yasg.codecs.
OpenAPICodecJson
(validators)¶ Bases:
drf_yasg.codecs._OpenAPICodec
-
_dump_dict
(spec)¶ Dump
spec
into JSON.
-
media_type
= 'application/json'¶
-
-
class
drf_yasg.codecs.
OpenAPICodecYaml
(validators)¶ Bases:
drf_yasg.codecs._OpenAPICodec
-
_dump_dict
(spec)¶ Dump
spec
into YAML.
-
media_type
= 'application/yaml'¶
-
-
class
drf_yasg.codecs.
_OpenAPICodec
(validators)¶ Bases:
object
-
_dump_dict
(spec)¶ Dump the given dictionary into its string representation.
Parameters: spec (dict) – a python dict Returns: string representation of spec
Return type: str
-
encode
(document)¶ Transform an
Swagger
object to a sequence of bytes.Also performs validation and applies settings.
Parameters: document (openapi.Swagger) – Swagger spec object as generated by OpenAPISchemaGenerator
Returns: binary encoding of document
Return type: bytes
-
encode_error
(err)¶ Dump an error message into an encoding-appropriate sequence of bytes
-
generate_swagger_object
(swagger)¶ Generates the root Swagger object.
Parameters: swagger (openapi.Swagger) – Swagger spec object as generated by OpenAPISchemaGenerator
Returns: swagger spec as dict Return type: OrderedDict
-
media_type
= None¶
-
validators
¶ List of validator names to apply
-
-
drf_yasg.codecs.
_validate_flex
(spec, codec)¶
-
drf_yasg.codecs.
_validate_swagger_spec_validator
(spec, codec)¶
-
drf_yasg.codecs.
yaml_sane_dump
(data, binary)¶ 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
Parameters: - data (dict) – the data to be serializers
- 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.
SwaggerError
¶ Bases:
Exception
-
exception
drf_yasg.errors.
SwaggerGenerationError
¶ Bases:
drf_yasg.errors.SwaggerError
-
exception
drf_yasg.errors.
SwaggerValidationError
(msg, validator_name, spec, source_codec, *args)¶ Bases:
drf_yasg.errors.SwaggerError
drf_yasg.generators¶
-
class
drf_yasg.generators.
OpenAPISchemaGenerator
(info, version, url=None, patterns=None, urlconf=None)¶ 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, takes preedence over the version in info
- url (str) – API
- 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
-
create_view
(callback, method, request=None)¶ 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=None)¶ Iterate over all the registered endpoints in the API.
Parameters: request (rest_framework.request.Request) – used for returning only endpoints available to the given request Returns: {path: (view_class, list[(http_method, view_instance)]) Return type: dict
-
get_operation_keys
(subpath, method, view)¶ 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
-
get_overrides
(view, method)¶ 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)¶ 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]
-
get_paths
(endpoints, components)¶ 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
Return type:
-
get_schema
(request=None, public=False)¶ Generate an
Swagger
representing the API schema.Parameters: - request (rest_framework.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:
drf_yasg.inspectors¶
-
class
drf_yasg.inspectors.
SwaggerAutoSchema
(view, path, method, overrides, components)¶ Bases:
object
Inspector class responsible for providing
Operation
definitions given aParameters: - view – the view associated with this endpoint
- path (str) – the path component of the operation URL
- method (str) – the http method of the operation
- overrides (dict) – manual overrides as passed to
@swagger_auto_schema
- components (openapi.ReferenceResolver) – referenceable components
-
add_manual_parameters
(parameters)¶ 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]
-
coreapi_field_to_parameter
(field)¶ Convert an instance of coreapi.Field to a swagger
Parameter
object.Parameters: field (coreapi.Field) – Return type: openapi.Parameter
-
field_to_parameter
(field, name, in_)¶ Convert a DRF serializer Field to a swagger
Parameter
object.Parameters: - field (coreapi.Field) –
- name (str) – the name of the parameter
- in (str) – the location of the parameter, one of the openapi.IN_* constants
Return type:
-
get_consumes
()¶ Return the MIME types this endpoint can consume.
Return type: list[str]
-
get_default_responses
()¶ Get the default responses determined for this view from the request serializer and request method.
Type: dict[str, openapi.Schema]
-
get_description
()¶ Return an operation description determined as appropriate from the view’s method and class docstrings.
Returns: the operation description Return type: str
-
get_filter_backend_parameters
(filter_backend)¶ Get the filter parameters for a single filter backend instance.
Parameters: filter_backend (BaseFilterBackend) – the filter backend Return type: list[openapi.Parameter]
-
get_filter_parameters
()¶ Return the parameters added to the view by its filter backends.
Return type: list[openapi.Parameter]
-
get_operation
(operation_keys)¶ 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_paged_response_schema
(response_schema)¶ Add appropriate paging fields to a response
Schema
.Parameters: response_schema (openapi.Schema) – the response schema that must be paged. Return type: openapi.Schema
-
get_pagination_parameters
()¶ Return the parameters added to the view by its paginator.
Return type: list[openapi.Parameter]
-
get_paginator_parameters
(paginator)¶ Get the pagination parameters for a single paginator instance.
Parameters: paginator (BasePagination) – the paginator Return type: list[openapi.Parameter]
-
get_query_parameters
()¶ Return the query parameters accepted by this view.
Return type: list[openapi.Parameter]
-
get_request_body_parameters
(consumes)¶ 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)¶ 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)¶ 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
()¶ 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)¶ 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
()¶ 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
()¶ Get the possible responses for this view as a swagger
Responses
object.Returns: the documented responses Return type: openapi.Responses
-
make_body_parameter
(schema)¶ Given a
Schema
object, create anin: body
Parameter
.Parameters: schema (openapi.Schema) – the request body schema Return type: openapi.Parameter
-
serializer_to_schema
(serializer)¶ Convert a DRF Serializer instance to an
openapi.Schema
.Parameters: serializer (serializers.BaseSerializer) – Return type: openapi.Schema
-
should_filter
()¶ Determine whether filter backend parameters should be included for this request.
Return type: bool
-
should_page
()¶ Determine whether paging parameters and structure should be added to this operation’s request and response.
Return type: bool
-
drf_yasg.inspectors.
force_serializer_instance
(serializer)¶ 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
drf_yasg.middleware¶
drf_yasg.openapi¶
-
class
drf_yasg.openapi.
Contact
(name=None, url=None, email=None, **extra)¶ 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.
Info
(title, default_version, description=None, terms_of_service=None, contact=None, license=None, **extra)¶ 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.
Items
(type=None, format=None, enum=None, pattern=None, items=None, **extra)¶ 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.
License
(name, url=None, **extra)¶ 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.
Operation
(operation_id, responses, parameters=None, consumes=None, produces=None, description=None, tags=None, **extra)¶ 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
- description (str) – operation description
- tags (list[str]) – operation tags
-
class
drf_yasg.openapi.
Parameter
(name, in_, description=None, required=None, schema=None, type=None, format=None, enum=None, pattern=None, items=None, **extra)¶ 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
-
class
drf_yasg.openapi.
PathItem
(get=None, put=None, post=None, delete=None, options=None, head=None, patch=None, parameters=None, **extra)¶ 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
-
class
drf_yasg.openapi.
Paths
(paths, **extra)¶ Bases:
drf_yasg.openapi.SwaggerDict
A listing of all the paths in the API.
Parameters: paths (dict[str,PathItem]) –
-
class
drf_yasg.openapi.
ReferenceResolver
(*scopes)¶ 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 -
_check_scope
(scope)¶
-
get
(name, scope=None)¶ 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)¶ 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)¶ 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
-
keys
()¶
-
scopes
¶
-
set
(name, obj, scope=None)¶ 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)¶ 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
-
with_scope
(scope)¶ Return a new
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
-
-
class
drf_yasg.openapi.
Response
(description, schema=None, examples=None, **extra)¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes the structure of an operation’s response.
Parameters:
-
class
drf_yasg.openapi.
Responses
(responses, default=None, **extra)¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes the expected responses of an
Operation
.Parameters:
-
class
drf_yasg.openapi.
Schema
(description=None, required=None, type=None, properties=None, additional_properties=None, format=None, enum=None, pattern=None, items=None, **extra)¶ Bases:
drf_yasg.openapi.SwaggerDict
Describes a complex object accepted as parameter or returned as a response.
Parameters: - description – schema description
- required (list[str]) – list of requried property names
- type (str) – value type; required
- properties (list[Schema,SchemaRef]) – object properties; required if type is
object
- additional_properties (bool,Schema,SchemaRef) – allow wildcard properties not listed in properties
- format (str) – value format, see OpenAPI spec
- enum (list) – restrict possible values
- pattern (str) – pattern if type is
string
- items (Schema,SchemaRef) – only valid if type is
array
-
OR_REF
= (<class 'drf_yasg.openapi.Schema'>, <class 'drf_yasg.openapi.SchemaRef'>)¶
-
class
drf_yasg.openapi.
SchemaRef
(resolver, schema_name)¶ 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
-
class
drf_yasg.openapi.
Swagger
(info=None, _url=None, _version=None, paths=None, definitions=None, **extra)¶ Bases:
drf_yasg.openapi.SwaggerDict
Root Swagger object.
Parameters:
-
class
drf_yasg.openapi.
SwaggerDict
(**attrs)¶ 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.
-
static
_as_odict
(obj)¶
-
_insert_extras__
()¶ From an ordering perspective, it is desired that extra attributes such as vendor extensions stay at the bottom of the object. However, python2.7’s OrderdDict craps out if you try to insert into it before calling init. This means that subclasses must call super().__init__ as the first statement of their own __init__, which would result in the extra attributes being added first. For this reason, we defer the insertion of the attributes and require that subclasses call ._insert_extras__ at the end of their __init__ method.
-
as_odict
()¶
-
static
-
class
drf_yasg.openapi.
_Ref
(resolver, name, scope, expected_type)¶ Bases:
drf_yasg.openapi.SwaggerDict
Base class for all reference types. A reference object has only one property,
$ref
, which must be a JSON reference to a valid object in the specification, e.g.#/definitions/Article
to refer to an article model.Parameters: - resolver (ReferenceResolver) – component resolver which must contain the referneced object
- name (str) – referenced object name, e.g. “Article”
- scope (str) – reference scope, e.g. “definitions”
- expected_type (type[SwaggerDict]) – the expected type that will be asserted on the object found in resolver
-
drf_yasg.openapi.
make_swagger_name
(attribute_name)¶ 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
drf_yasg.renderers¶
-
class
drf_yasg.renderers.
OpenAPIRenderer
¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a JSON document with the
application/openapi+json
specific mime type.-
codec_class
¶ alias of
OpenAPICodecJson
-
format
= 'openapi'¶
-
media_type
= 'application/openapi+json'¶
-
-
class
drf_yasg.renderers.
ReDocRenderer
¶ Bases:
drf_yasg.renderers._UIRenderer
Renders a ReDoc web interface for schema browisng. Also requires
OpenAPIRenderer
as an available renderer on the same view.-
format
= 'redoc'¶
-
template
= 'drf-yasg/redoc.html'¶
-
-
class
drf_yasg.renderers.
SwaggerJSONRenderer
¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a JSON document with the generic
application/json
mime type.-
codec_class
¶ alias of
OpenAPICodecJson
-
format
= '.json'¶
-
media_type
= 'application/json'¶
-
-
class
drf_yasg.renderers.
SwaggerUIRenderer
¶ Bases:
drf_yasg.renderers._UIRenderer
Renders a swagger-ui web interface for schema browisng. Also requires
OpenAPIRenderer
as an available renderer on the same view.-
format
= 'swagger'¶
-
template
= 'drf-yasg/swagger-ui.html'¶
-
-
class
drf_yasg.renderers.
SwaggerYAMLRenderer
¶ Bases:
drf_yasg.renderers._SpecRenderer
Renders the schema as a YAML document.
-
codec_class
¶ alias of
OpenAPICodecYaml
-
format
= '.yaml'¶
-
media_type
= 'application/yaml'¶
-
-
class
drf_yasg.renderers.
_SpecRenderer
¶ Bases:
rest_framework.renderers.BaseRenderer
Base class for text renderers. Handles encoding and validation.
-
charset
= None¶
-
codec_class
= None¶
-
render
(data, media_type=None, renderer_context=None)¶
-
validators
= ['ssv', 'flex']¶
-
classmethod
with_validators
(validators)¶
-
-
class
drf_yasg.renderers.
_UIRenderer
¶ Bases:
rest_framework.renderers.BaseRenderer
Base class for web UI renderers. Handles loading an passing settings to the appropriate template.
-
charset
= 'utf-8'¶
-
get_auth_urls
()¶
-
get_redoc_settings
()¶
-
get_swagger_ui_settings
()¶
-
media_type
= 'text/html'¶
-
render
(swagger, accepted_media_type=None, renderer_context=None)¶
-
set_context
(renderer_context, swagger)¶
-
template
= ''¶
-
drf_yasg.utils¶
-
drf_yasg.utils.
find_regex
(regex_field)¶ Given a
Field
, look for aRegexValidator
and try to extract its pattern and return it as a string.Parameters: regex_field (serializers.Field) – the field instance Returns: the extracted pattern, or None
Return type: str
-
drf_yasg.utils.
is_list_view
(path, method, view)¶ 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.
serializer_field_to_swagger
(field, swagger_object_type, definitions=None, **kwargs)¶ Convert a drf Serializer or Field instance into a Swagger object.
Parameters: - field (rest_framework.serializers.Field) – the source field
- swagger_object_type (type[openapi.SwaggerDict]) – should be one of Schema, Parameter, Items
- definitions (ReferenceResolver) – used to serialize Schemas by reference
- kwargs – extra attributes for constructing the object;
if swagger_object_type is Parameter,
name
andin_
should be provided
Returns: the swagger object
Return type:
-
drf_yasg.utils.
swagger_auto_schema
(method=None, methods=None, auto_schema=None, request_body=None, manual_parameters=None, operation_description=None, responses=None)¶ 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 (SwaggerAutoSchema) – custom class to use for generating the Operation object
- 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. - 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_description (str) – operation description override
- 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 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
drf_yasg.views¶
-
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.
-
_ignore_model_permissions
= True¶
-
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
¶ alias of
OpenAPISchemaGenerator
-
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
-
-
drf_yasg.views.
deferred_never_cache
(view_func)¶ Decorator that adds headers to a response so that it will never be cached.
-
drf_yasg.views.
get_schema_view
(info, url=None, patterns=None, urlconf=None, public=False, validators=None, generator_class=<class 'drf_yasg.generators.OpenAPISchemaGenerator'>, authentication_classes=[<class 'rest_framework.authentication.SessionAuthentication'>, <class 'rest_framework.authentication.BasicAuthentication'>], permission_classes=[<class 'rest_framework.permissions.AllowAny'>])¶ Create a SchemaView class with default renderers and generators.
Parameters: - info (Info) – Required. Swagger API Info object
- url (str) – API base url; if left blank will be deduced from the location the view is served at
- patterns – passed to SchemaGenerator
- urlconf – passed to SchemaGenerator
- public (bool) – if False, includes only endpoints the current user has access to
- 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]