openapi.rst

Functional overview

OpenAPI specification overview

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.

• .Swagger object

  • info, schemes, securityDefinitions and other informative attributes

  • paths: .Paths object

    A list of all the paths in the API in the form of a mapping

    • {path}: .PathItem - each .PathItem has multiple operations keyed by method

      • {http_method}: .Operation

        Each operation is thus uniquely identified by its (path, http_method) combination, e.g. GET /articles/, POST /articles/, etc.

      • parameters: [.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}: .Schema

• .Operation contains the following information about each operation:

  • parameters: [.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 .Schema or a reference to one (.SchemaRef)

  • responses: .Responses

    A list of all the possible responses the operation is expected to return. Each response can optionally have a .Schema which describes the structure of its body.

    • {status_code}: .Response - mapping of status code to response definition

  • operationId - should be unique across all operations
  • tags - used to group operations in the listing

It is interesting to note the main differences between .Parameter and .Schema objects:

.Schema	.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 .Operation1
Can be used in .Responses	Cannot be used in .Responses
Cannot be used in form .Operations2	Can be used in form .Operations3
Can only describe request or response bodies	Can describe query, form, header or path parameters

Default behavior

This section describes where information is sourced from when using the default generation process.

• .Paths are generated by exploring the patterns registered in your default urlconf, or the patterns and urlconf you specified when constructing .OpenAPISchemaGenerator; only views inheriting from Django Rest Framework's APIView are looked at, all other views are ignored
• path .Parameters are generated by looking in the URL pattern for any template parameters; attempts are made to guess their type from the views queryset and lookup_field, if applicable. You can override path parameters via manual_parameters in @swagger_auto_schema <custom-spec-swagger-auto-schema>.
• query .Parameters - i.e. parameters specified in the URL as /path/?query1=value&query2=value -are generated from your view's filter_backends and paginator, if any are declared. Additional parameters can be specified via the query_serializer and manual_parameters arguments of @swagger_auto_schema <custom-spec-swagger-auto-schema>

• The request body is only generated for the HTTP POST, PUT and PATCH methods, and is sourced from the view's serializer_class. You can also override the request body using the request_body argument of @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 or application/x-www-form-urlencoded media types), the request body will be output as form .Parameters
  • if it is not a form request, the request body will be output as a single body .Parameter wrapped around a .Schema

• header .Parameters are supported by the OpenAPI specification but are never generated by this library; you can still add them using manual_parameters.

• .Responses are generated as follows:

  • if responses is provided to @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 @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` forDELETErequests,201forPOSTrequests, and200`` for all other request methods
    • if the view has a request body, the same Serializer or .Schema as in the request body is used in generating the .Response schema; this is inline with the default GenericAPIView and GenericViewSet behavior
    • if the view has no request body, its serializer_class is used to generate the .Response schema
    • if the view is a list view (as defined by .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

• .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 .Response object
• descriptions for .Operations, .Parameters and .Schemas are picked up from docstrings and help_text attributes in the same manner as the default DRF SchemaGenerator

• The base URL for the API consists of three values - the host, schemes and basePath attributes

• The host name and scheme are determined, in descending order of priority:

  • from the url argument passed to .get_schema_view (more specifically, to the underlying .OpenAPISchemaGenerator)
  • from the 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 the host and schemes attributes with www.example.com:8080 and ['https'], respectively. The path component will be ignored.

• The base path is determined as the concatenation of two variables:

  1. 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.

  2. the longest common path prefix of all the urls in your API - see .determine_path_prefix

• When using API versioning with NamespaceVersioning or URLPathVersioning, versioned endpoints that do not match the version used to access the SchemaView 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 not

  Other versioning schemes are not presently supported.

A note on limitations

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 @swagger_auto_schema <custom-spec-swagger-auto-schema>, to prevent get_serializer from being called on the view
• exclude your endpoint from introspection <custom-spec-excluding-endpoints>

---

1. a form Operation is an .Operation that consumes multipart/form-data or application/x-www-form-urlencoded content

   • a form Operation cannot have body parameters
   • a non-form operation cannot have form parameters

   ↩

2. a form Operation is an .Operation that consumes multipart/form-data or application/x-www-form-urlencoded content

   • a form Operation cannot have body parameters
   • a non-form operation cannot have form parameters

   ↩

3. a form Operation is an .Operation that consumes multipart/form-data or application/x-www-form-urlencoded content

   • a form Operation cannot have body parameters
   • a non-form operation cannot have form parameters

   ↩