This library generates OpenAPI 2.0 documents. The authoritative specification for this document's structure will always be the official documentation over at swagger.io and the OpenAPI 2.0 specification page.
Beause the above specifications are a bit heavy and convoluted, here is a general overview of how the specification
is structured, starting from the root Swagger
object.
- :class:`.Swagger` object
info
,schemes
,securityDefinitions
and other informative attributespaths
: :class:`.Paths` object- A list of all the paths in the API in the form of a mapping
{path}
: :class:`.PathItem` - each :class:`.PathItem` has multiple operations keyed by method{http_method}
: :class:`.Operation`- Each operation is thus uniquely identified by its
(path, http_method)
combination, e.g.GET /articles/
,POST /articles/
, etc.
parameters
: [:class:`.Parameter`] - and a list of path parameters
definitions
: named Models- A list of all the named models in the API in the form of a mapping
{ModelName}
: :class:`.Schema`
- :class:`.Operation` contains the following information about each operation:
parameters
: [:class:`.Parameter`]- A list of all the query, header and form parameters accepted by the operation.
- there can also be at most one body parameter whose structure is represented by a :class:`.Schema` or a reference to one (:class:`.SchemaRef`)
responses
: :class:`.Responses`- A list of all the possible responses the operation is expected to return. Each response can optionally have a
:class:`.Schema` which describes the structure of its body.
{status_code}
: :class:`.Response` - mapping of status code to response definition
operationId
- should be unique across all operationstags
- used to group operations in the listing
It is interesting to note the main differences between :class:`.Parameter` and :class:`.Schema` objects:
:class:`.Schema` | :class:`.Parameter` |
---|---|
Can nest other Schemas | Cannot nest other Parameters Can only nest a Schema if the parameter is in: body |
Cannot describe file uploads - file is not permitted as a value for type |
Can describe file uploads via type = file , but only as part of a form :class:`.Operation` [1] |
Can be used in :class:`.Response`s | Cannot be used in :class:`.Response`s |
Cannot be used in form :class:`.Operation`s [1] | Can be used in form :class:`.Operation`s [1] |
Can only describe request or response bodies | Can describe query , form , header or path
parameters |
[1] | (1, 2, 3) a form Operation is an :class:`.Operation` that consumes
|
This section describes where information is sourced from when using the default generation process.
:class:`.Paths` are generated by exploring the patterns registered in your default
urlconf
, or thepatterns
andurlconf
you specified when constructing :class:`.OpenAPISchemaGenerator`; only views inheriting from Django Rest Framework'sAPIView
are looked at, all other views are ignoredpath
:class:`.Parameter`s are generated by looking in the URL pattern for any template parameters; attempts are made to guess their type from the viewsqueryset
andlookup_field
, if applicable. You can override path parameters viamanual_parameters
in :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`.query
:class:`.Parameter`s - i.e. parameters specified in the URL as/path/?query1=value&query2=value
- are generated from your view'sfilter_backends
andpaginator
, if any are declared. Additional parameters can be specified via thequery_serializer
andmanual_parameters
arguments of :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`The request body is only generated for the HTTP
POST
,PUT
andPATCH
methods, and is sourced from the view'sserializer_class
. You can also override the request body using therequest_body
argument of :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`.- if the view represents a form request (that is, all its parsers are of the
multipart/form-data
orapplication/x-www-form-urlencoded
media types), the request body will be output asform
:class:`.Parameter`s - if it is not a form request, the request body will be output as a single
body
:class:`.Parameter` wrapped around a :class:`.Schema`
- if the view represents a form request (that is, all its parsers are of the
header
:class:`.Parameter`s are supported by the OpenAPI specification but are never generated by this library; you can still add them usingmanual_parameters
.:class:`.Responses` are generated as follows:
if
responses
is provided to :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>` and contains at least one success status code (i.e. any 2xx status code), no automatic response is generated and the given response is used as described in the :func:`@swagger_auto_schema documentation <.swagger_auto_schema>`otherwise, an attempt is made to generate a default response:
- the success status code is assumed to be
204` for ``DELETE
requests,201
forPOST
requests, and200
for all other request methods - if the view has a request body, the same
Serializer
or :class:`.Schema` as in the request body is used in generating the :class:`.Response` schema; this is inline with the defaultGenericAPIView
andGenericViewSet
behavior - if the view has no request body, its
serializer_class
is used to generate the :class:`.Response` schema - if the view is a list view (as defined by :func:`.is_list_view`), the response schema is wrapped in an array
- if the view is also paginated, the response schema is then wrapped in the appropriate paging response structure
- the description of the response is left blank
- the success status code is assumed to be
:class:`.Response` headers are supported by the OpenAPI specification but not currently supported by this library; you can still add them manually by providing an appropriately structured dictionary to the
headers
property of a :class:`.Response` objectdescriptions for :class:`.Operation`s, :class:`.Parameter`s and :class:`.Schema`s are picked up from docstrings and
help_text
attributes in the same manner as the default DRF SchemaGeneratorThe base URL for the API consists of three values - the
host
,schemes
andbasePath
attributesThe host name and scheme are determined, in descending order of priority:
- from the
url
argument passed to :func:`.get_schema_view` (more specifically, to the underlying :class:`.OpenAPISchemaGenerator`) - from the :ref:`DEFAULT_API_URL setting <default-swagger-settings>`
- inferred from the request made to the schema endpoint
For example, an url of
https://www.example.com:8080/some/path
will populate thehost
andschemes
attributes withwww.example.com:8080
and['https']
, respectively. The path component will be ignored.- from the
The base path is determined as the concatenation of two variables:
the SCRIPT_NAME wsgi environment variable; this is set, for example, when serving the site from a sub-path using web server url rewriting
Tip
The Django FORCE_SCRIPT_NAME setting can be used to override the SCRIPT_NAME or set it when it's missing from the environment.
the longest common path prefix of all the urls in your API - see :meth:`.determine_path_prefix`
When using API versioning with
NamespaceVersioning
orURLPathVersioning
, versioned endpoints that do not match the version used to access theSchemaView
will be excluded from the endpoint list - for example,/api/v1.0/endpoint
will be shown when viewing/api/v1.0/swagger/
, while/api/v2.0/endpoint
will notOther versioning schemes are not presently supported.
When schema generation is requested, available endpoints are inspected by enumeration all the routes registered in Django's urlconf. Each registered view is then artificially instantiated for introspection, and it is this step that brings some limitations to what can be done:
- the
request
the view sees will always be the request made against the schema view endpoint - e.g.GET /swagger.yaml
- path parameters will not be filled
This means that you could get surprizing results if your get_serializer
or get_serializer_class
methods
depend on the incoming request, call get_object
or in general depend on any stateful logic. You can prevent this
in a few ways:
- provide a fixed serializer for request and response body introspection using
:ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`, to prevent
get_serializer
from being called on the view - :ref:`exclude your endpoint from introspection <custom-spec-excluding-endpoints>`