Add 1.3.1 changelog

Add documentation about excluding endpoints
Closes #50.
2018-01-24 17:43:38 +02:00 · 2018-01-24 17:38:10 +02:00 · 2018-01-24 14:44:00 +02:00 · 2018-01-23 12:44:16 +02:00 · 2018-01-23 12:43:25 +02:00 · 2018-01-19 18:37:44 +01:00
31 changed files with 519 additions and 373 deletions
@@ -20,7 +20,10 @@ exclude_lines =
    raise TypeError
    raise NotImplementedError
    warnings.warn
+    logger.debug
+    logger.info
    logger.warning
+    logger.error
    return NotHandled

    # Don't complain if non-runnable code isn't run:
@@ -24,10 +24,8 @@ jobs:

    - stage: publish
      python: '3.6'
-      before_script: skip
      script: skip
-      after_success: skip
-      env:
+      env: PYPI_DEPLOY=true
      deploy: &pypi
        provider: pypi
        user: cvijdea
@@ -49,7 +47,7 @@ install:
 before_script:
 - coverage erase
 - |
-  [[ -z "$TOXENV" ]] && REPORT_COVERAGE="yes" || REPORT_COVERAGE="no";
+  [[ -z "$TOXENV" && -z "$PYPI_DEPLOY" ]] && REPORT_COVERAGE="yes" || REPORT_COVERAGE="no";
  echo "Reporting coverage: ${REPORT_COVERAGE}"
 - |
  [[ -z "$TOXENV" && ! -z "$DRF" && "$DRF" != "master" ]] && USE_DETOX="yes" || USE_DETOX="no";
@@ -103,16 +103,17 @@ Maintainer's notes
 Release checklist
 =================

-* update ``docs/changelog.rst`` with changes since the latest tag
-* commit & tag the release
+* update ``docs/changelog.rst`` with changes since the last tagged version
+* commit & tag the release - ``git tag x.x.x -m "Release version x.x.x"``
 * push using ``git push --follow-tags``
-* verify that `Travis`_ has built the tag and succesfully published the release to PyPI
+* verify that `Travis`_ has built the tag and succesfully published the release to `PyPI`_
 * publish release notes `on GitHub`_
 * start the `ReadTheDocs build`_ if it has not already started
 * deploy the live demo `on Heroku`_


 .. _Travis: https://travis-ci.org/axnsan12/drf-yasg/builds
+.. _PyPI: https://pypi.org/project/drf-yasg/
 .. _on GitHub: https://github.com/axnsan12/drf-yasg/releases
 .. _ReadTheDocs build: https://readthedocs.org/projects/drf-yasg/builds/
 .. _on Heroku: https://dashboard.heroku.com/pipelines/412d1cae-6a95-4f5e-810b-94869133f36a
@@ -11,8 +11,8 @@ Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framewor

 Compatible with

- **Django Rest Framework**: 3.7
- **Django**: 1.11, 2.0
+- **Django Rest Framework**: 3.7.7
+- **Django**: 1.11.x, 2.0.x
 - **Python**: 2.7, 3.4, 3.5, 3.6

 Resources:
@@ -42,10 +42,8 @@ Features
 - generated Swagger schema can be automatically validated by
  `swagger-spec-validator <https://github.com/Yelp/swagger_spec_validator>`_ or
  `flex <https://github.com/pipermerriam/flex>`_
- supports Django REST Framework API versioning
-
-   + ``URLPathVersioning`` and ``NamespaceVersioning`` are supported
-   + ``HostnameVersioning``, ``AcceptHeaderVersioning`` and ``QueryParameterVersioning`` are not currently supported
+- supports Django REST Framework API versioning with ``URLPathVersioning`` and ``NamespaceVersioning``; other DRF
+  or custom versioning schemes are not currently supported

 .. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/redoc-nested-response.png
   :width: 100%
@@ -187,71 +185,8 @@ c. ``SWAGGER_SETTINGS`` and ``REDOC_SETTINGS``
 ----------------------------------------------

 Additionally, you can include some more settings in your ``settings.py`` file.
-The possible settings and their default values are as follows:
+See https://drf-yasg.readthedocs.io/en/stable/settings.html for details.

-.. code:: python
-
-   SWAGGER_SETTINGS = {
-      # default inspector classes, see advanced documentation
-      'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
-      'DEFAULT_FIELD_INSPECTORS': [
-         'drf_yasg.inspectors.CamelCaseJSONFilter',
-         'drf_yasg.inspectors.ReferencingSerializerInspector',
-         'drf_yasg.inspectors.RelatedFieldInspector',
-         'drf_yasg.inspectors.ChoiceFieldInspector',
-         'drf_yasg.inspectors.FileFieldInspector',
-         'drf_yasg.inspectors.DictFieldInspector',
-         'drf_yasg.inspectors.SimpleFieldInspector',
-         'drf_yasg.inspectors.StringDefaultFieldInspector',
-      ],
-      'DEFAULT_FILTER_INSPECTORS': [
-         'drf_yasg.inspectors.CoreAPICompatInspector',
-      ],
-      'DEFAULT_PAGINATOR_INSPECTORS': [
-         'drf_yasg.inspectors.DjangoRestResponsePagination',
-         'drf_yasg.inspectors.CoreAPICompatInspector',
-      ],
-
-      # default api Info if none is otherwise given; should be an import string to an openapi.Info object
-      'DEFAULT_INFO': None,
-      # default API url if none is otherwise given
-      'DEFAULT_API_URL': None,
-
-      'USE_SESSION_AUTH': True,  # add Django Login and Django Logout buttons, CSRF token to swagger UI page
-      'LOGIN_URL': getattr(django.conf.settings, 'LOGIN_URL', None),  # URL for the login button
-      'LOGOUT_URL': getattr(django.conf.settings, 'LOGOUT_URL', None),  # URL for the logout button
-
-      # Swagger security definitions to include in the schema;
-      # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object
-      'SECURITY_DEFINITIONS': {
-         'basic': {
-            'type': 'basic'
-         }
-      },
-
-      # url to an external Swagger validation service; defaults to 'http://online.swagger.io/validator/'
-      # set to None to disable the schema validation badge in the UI
-      'VALIDATOR_URL': '',
-
-      # swagger-ui configuration settings, see https://github.com/swagger-api/swagger-ui/blob/112bca906553a937ac67adc2e500bdeed96d067b/docs/usage/configuration.md#parameters
-      'OPERATIONS_SORTER': None,
-      'TAGS_SORTER': None,
-      'DOC_EXPANSION': 'list',
-      'DEEP_LINKING': False,
-      'SHOW_EXTENSIONS': True,
-      'DEFAULT_MODEL_RENDERING': 'model',
-      'DEFAULT_MODEL_DEPTH': 3,
-   }
-
-.. code:: python
-
-   REDOC_SETTINGS = {
-      # ReDoc UI configuration settings, see https://github.com/Rebilly/ReDoc#redoc-tag-attributes
-      'LAZY_RENDERING': True,
-      'HIDE_HOSTNAME': False,
-      'EXPAND_RESPONSES': 'all',
-      'PATH_IN_MIDDLE': False,
-   }

 3. Caching
 ==========
@@ -2,6 +2,38 @@
 Changelog
 #########

+*********
+**1.3.1**
+*********
+
+- **FIXED:** fixed a bug that would sometimes cause endpoints to wrongly be output as form operations (:issue:`50`)
+- **IMPROVED:** added generation of ``produces`` based on renderer classes
+- **IMPROVED:** added generation of top-level ``consumes`` and ``produces`` based on
+  ``DEFAULT_PARSER_CLASSES`` and ``DEFAULT_RENDERER_CLASSES`` (:issue:`48`)
+
+*********
+**1.3.0**
+*********
+
+- **ADDED:** security requirements are now correctly set and can be customized; this should fix problems related
+  to authentication in ``swagger-ui`` Try it out!  (:issue:`50`, :pr:`54`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.9.2
+- **IMPROVED:** updated ``ReDoc`` to version 1.20.0
+- **FIXED:** fixed an exception caused by a warning in get_path_from_regex (:pr:`49`, thanks to :ghuser:`blueyed`)
+
+*********
+**1.2.2**
+*********
+
+- **FIXED:** djangorestframework>=3.7.7 is now required because of breaking changes
+  (:issue:`44`, :pr:`45`, thanks to :ghuser:`h-hirokawa`)
+
+*********
+**1.2.1**
+*********
+
+- Fixed deployment issues
+
 *********
 **1.2.0**
 *********
@@ -9,157 +9,30 @@ Custom schema generation
 If the default spec generation does not quite match what you were hoping to achieve, ``drf-yasg`` provides some
 custom behavior hooks by default.

-*********************
-Swagger spec overview
-*********************
+.. _custom-spec-excluding-endpoints:

-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 <https://swagger.io/>`__ and the `OpenAPI 2.0 specification
-page <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>`__.
+*******************
+Excluding endpoints
+*******************

-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.
+You can prevent a view from being included in the Swagger view by setting its class-level ``swagger_schema``
+attribute to ``None``, or you can prevent an operation from being included by setting its ``auto_schema`` override
+to none in :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`:

-* :class:`.Swagger` object
-   + ``info``, ``schemes``, ``securityDefinitions`` and other informative attributes
-   + ``paths``: :class:`.Paths` object
-      A list of all the paths in the API in the form of a mapping
+.. code-block:: python

-      - ``{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
+   class UserList(APIView):
+      swagger_schema = None

-      - ``{ModelName}``: :class:`.Schema`
+      # all methods of the UserList class will be excluded
+      ...

-* :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 operations
-   + ``tags`` - 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 |br|                         |
-|                                                          | Can only nest a Schema if the parameter is ``in: body``   |
-+----------------------------------------------------------+-----------------------------------------------------------+
-| Cannot describe file uploads |br|                        | Can describe file uploads via ``type`` = ``file``, |br|   |
-| - ``file`` is not permitted as a value for ``type``      | but only as part of a form :class:`.Operation` [#formop]_ |
-+----------------------------------------------------------+-----------------------------------------------------------+
-| Can be used in :class:`.Response`\ s                     | Cannot be used in :class:`.Response`\ s                   |
-+----------------------------------------------------------+-----------------------------------------------------------+
-| Cannot be used in form :class:`.Operation`\ s [#formop]_ | Can be used in form :class:`.Operation`\ s [#formop]_     |
-+----------------------------------------------------------+-----------------------------------------------------------+
-| Can only describe request or response bodies             | Can describe ``query``, ``form``, ``header`` or ``path``  |
-|                                                          | parameters                                                |
-+----------------------------------------------------------+-----------------------------------------------------------+
-
-.. [#formop] a form Operation is an :class:`.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
-
-****************
-Default behavior
-****************
-
-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 the ``patterns``
-  and ``urlconf`` you specified when constructing :class:`.OpenAPISchemaGenerator`; only views inheriting from Django
-  Rest Framework's ``APIView`` are looked at, all other views are ignored
-* ``path`` :class:`.Parameter`\ s 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 :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's ``filter_backends`` and ``paginator``, if any are declared. Additional parameters can
-  be specified via the ``query_serializer`` and ``manual_parameters`` arguments of
-  :ref:`@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
-  :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`` or
-     ``application/x-www-form-urlencoded`` media types), the request body will be output as ``form``
-     :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`
-
-* ``header`` :class:`.Parameter`\ s are supported by the OpenAPI specification but are never generated by this library;
-  you can still add them using ``manual_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`` for ``POST`` requests, and
-        ``200`` 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 default ``GenericAPIView`` and
-        ``GenericViewSet`` 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
-
-* :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
-  <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#headersObject>`_
-  to the ``headers`` property of a :class:`.Response` object
-* *descriptions* 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 SchemaGenerator
-  <http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation>`_
-* .. _custom-spec-base-url:
-
-  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 :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 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:
-
-   #. 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`` 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.
-
-
-.. versionadded:: 1.2
-   Base path and versioning support.
+   # only the GET method will be shown in Swagger
+   @swagger_auto_schema(method='put', auto_schema=None)
+   @swagger_auto_schema(methods=['get'], ...)
+   @api_view(['GET', 'PUT'])
+   def user_detail(request, pk):
+      pass

 .. _custom-spec-swagger-auto-schema:

@@ -352,8 +225,6 @@ This custom generator can be put to use by setting it as the :attr:`.generator_c
 ``Inspector`` classes
 ---------------------

-.. versionadded:: 1.1
-
 For customizing behavior related to specific field, serializer, filter or paginator classes you can implement the
 :class:`~.inspectors.FieldInspector`, :class:`~.inspectors.SerializerInspector`, :class:`~.inspectors.FilterInspector`,
 :class:`~.inspectors.PaginatorInspector` classes and use them with
@@ -430,6 +301,3 @@ A second example, of a :class:`~.inspectors.FieldInspector` that removes the ``t
   This means that you should generally avoid view or method-specific ``FieldInspector``\ s if you are dealing with
   references (a.k.a named models), because you can never know which view will be the first to generate the schema
   for a given serializer.
-
-.. _SCRIPT_NAME: https://www.python.org/dev/peps/pep-0333/#environ-variables
-.. _FORCE_SCRIPT_NAME: https://docs.djangoproject.com/en/2.0/ref/settings/#force-script-name
@@ -12,6 +12,8 @@ drf-yasg

   readme.rst
   rendering.rst
+   openapi.rst
+   security.rst
   custom_spec.rst
   custom_ui.rst
   settings.rst
@@ -0,0 +1,179 @@
+.. |br| raw:: html
+
+   <br />
+
+**********************
+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 <https://swagger.io/>`__ and the `OpenAPI 2.0 specification
+page <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>`__.
+
+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 attributes
+   + ``paths``: :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 operations
+   + ``tags`` - 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 |br|                         |
+|                                                          | Can only nest a Schema if the parameter is ``in: body``   |
+----------------------------------------------------------+-----------------------------------------------------------+
+| Cannot describe file uploads |br|                        | Can describe file uploads via ``type`` = ``file``, |br|   |
+| - ``file`` is not permitted as a value for ``type``      | but only as part of a form :class:`.Operation` [#formop]_ |
+----------------------------------------------------------+-----------------------------------------------------------+
+| Can be used in :class:`.Response`\ s                     | Cannot be used in :class:`.Response`\ s                   |
+----------------------------------------------------------+-----------------------------------------------------------+
+| Cannot be used in form :class:`.Operation`\ s [#formop]_ | Can be used in form :class:`.Operation`\ s [#formop]_     |
+----------------------------------------------------------+-----------------------------------------------------------+
+| Can only describe request or response bodies             | Can describe ``query``, ``form``, ``header`` or ``path``  |
+|                                                          | parameters                                                |
+----------------------------------------------------------+-----------------------------------------------------------+
+
+.. [#formop] a form Operation is an :class:`.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
+
+----------------
+Default behavior
+----------------
+
+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 the ``patterns``
+  and ``urlconf`` you specified when constructing :class:`.OpenAPISchemaGenerator`; only views inheriting from Django
+  Rest Framework's ``APIView`` are looked at, all other views are ignored
+* ``path`` :class:`.Parameter`\ s 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 :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's ``filter_backends`` and ``paginator``, if any are declared. Additional parameters can
+  be specified via the ``query_serializer`` and ``manual_parameters`` arguments of
+  :ref:`@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
+  :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`` or
+     ``application/x-www-form-urlencoded`` media types), the request body will be output as ``form``
+     :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`
+
+* ``header`` :class:`.Parameter`\ s are supported by the OpenAPI specification but are never generated by this library;
+  you can still add them using ``manual_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`` for ``POST`` requests, and
+        ``200`` 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 default ``GenericAPIView`` and
+        ``GenericViewSet`` 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
+
+* :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
+  <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#headersObject>`_
+  to the ``headers`` property of a :class:`.Response` object
+* *descriptions* 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 SchemaGenerator
+  <http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation>`_
+* .. _custom-spec-base-url:
+
+  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 :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 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:
+
+   #. 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`` 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
+  :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>`
+
+.. _SCRIPT_NAME: https://www.python.org/dev/peps/pep-0333/#environ-variables
+.. _FORCE_SCRIPT_NAME: https://docs.djangoproject.com/en/2.0/ref/settings/#force-script-name
@@ -41,8 +41,6 @@ You can use your custom renderer classes as kwargs to :meth:`.SchemaView.as_cach
 Management command
 ******************

-.. versionadded:: 1.1.1
-
 If you only need a swagger spec file in YAML or JSON format, you can use the ``generate_swagger`` management command
 to get it without having to start the web server:

@@ -0,0 +1,49 @@
+*********************************
+Describing authentication schemes
+*********************************
+
+When using the `swagger-ui` frontend, it is possible to interact with the API described by your Swagger document.
+This interaction might require authentication, which you will have to describe in order to make `swagger-ui` work
+with it.
+
+
+--------------------
+Security definitions
+--------------------
+
+The first step that you have to do is add a :ref:`SECURITY_DEFINITIONS <security-definitions-settings>` setting
+to declare all authentication schemes supported by your API.
+
+For example, the definition for a simple API accepting HTTP basic auth and `Authorization` header API tokens would be:
+
+.. code-block:: python
+
+   SWAGGER_SETTINGS = {
+      'SECURITY_DEFINITIONS': {
+         'Basic': {
+               'type': 'basic'
+         },
+         'Bearer': {
+               'type': 'apiKey',
+               'name': 'Authorization',
+               'in': 'header'
+         }
+      }
+   }
+
+
+---------------------
+Security requirements
+---------------------
+
+The second step is specifying, for each endpoint, which authentication mechanism can be used for interacting with it.
+See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object for details.
+
+By default, a top-level `security` that accepts all the declared security definitions is generated.
+For the example above, that would be :code:`[{'Basic': []}, {'Bearer': []}]`. This can be overriden using the
+:ref:`SECURITY_REQUIREMENTS <security-definitions-settings>` setting.
+
+Operation-level overrides can be added using the ``security`` parameter of
+:ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`.
+
+
@@ -140,6 +140,9 @@ URL for the Django Logout action when using `USE_SESSION_AUTH`_.

 **Default**: :python:`django.conf.settings.LOGOUT_URL`

+.. _security-definitions-settings:
+
+
 SECURITY_DEFINITIONS
 --------------------

@@ -154,6 +157,14 @@ See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#sec
      'type': 'basic'
   }

+SECURITY_REQUIREMENTS
+---------------------
+
+Global security requirements. If :python:`None`, all schemes in ``SECURITY_DEFINITIONS`` are accepted. |br|
+See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject.
+
+**Default**: :python:`None`
+
 .. _swagger-ui-settings:

 Swagger UI settings
@@ -38,9 +38,9 @@
      }
    },
    "commander": {
-      "version": "2.12.2",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-2.12.2.tgz",
-      "integrity": "sha512-BFnaq5ZOGcDN7FlrtBT4xxkgIToalIIxwjxLWVJ8bGTpe1LroqMiqQXdA7ygc7CRvaYS+9zfPGFnJqFSayx+AA==",
+      "version": "2.13.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-2.13.0.tgz",
+      "integrity": "sha512-MVuS359B+YzaWqjCL/c+22gfryv+mCBPHAv3zyVI2GN8EY6IRP8VwtasXn8jyyhvvq84R4ImN1OKRtcbIasjYA==",
      "optional": true
    },
    "core-js": {
@@ -73,9 +73,9 @@
      "integrity": "sha1-8TyUAhQdoJ50rfTmN5jXkiBEOPI="
    },
    "es6-promise": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-4.1.1.tgz",
-      "integrity": "sha512-OaU1hHjgJf+b0NzsxCg7NdIYERD6Hy/PEmFLTjw+b65scuisG3Kt4QoTvJ66BBkPZ581gr0kpoVzKnxniM8nng=="
+      "version": "4.2.2",
+      "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-4.2.2.tgz",
+      "integrity": "sha512-LSas5vsuA6Q4nEdf9wokY5/AJYXry98i0IzXsv49rYsgDGDNDPbqAYR1Pe23iFxygfbGZNR/5VrHXBCh2BhvUQ=="
    },
    "esprima": {
      "version": "4.0.0",
@@ -145,9 +145,9 @@
      "requires": {
        "call-me-maybe": "1.0.1",
        "debug": "3.1.0",
-        "es6-promise": "4.1.1",
+        "es6-promise": "4.2.2",
        "js-yaml": "3.10.0",
-        "ono": "4.0.2",
+        "ono": "4.0.3",
        "z-schema": "3.19.0"
      }
    },
@@ -166,15 +166,20 @@
      "resolved": "https://registry.npmjs.org/lunr/-/lunr-1.0.0.tgz",
      "integrity": "sha1-XJJ2ySyRrDWpJBtQGNRnI9kuL18="
    },
+    "mark.js": {
+      "version": "8.11.1",
+      "resolved": "https://registry.npmjs.org/mark.js/-/mark.js-8.11.1.tgz",
+      "integrity": "sha1-GA8fnr74sOY45BZq1S24eb6y/8U="
+    },
    "ms": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
      "integrity": "sha1-VgiurfwAvmwpAd9fmGF4jeDVl8g="
    },
    "ono": {
-      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/ono/-/ono-4.0.2.tgz",
-      "integrity": "sha512-EFXJFoeF+KkZW4lwmcPMKHp2ZU7o6CM+ccX2nPbEJKiJIdyqbIcS1v6pmNgeNJ6x4/vEYn0/8oz66qXSPnnmSQ==",
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/ono/-/ono-4.0.3.tgz",
+      "integrity": "sha512-7QIxG4UB00H7CR7fhXC/U7VhB5DK9wsYLwaYBui1JmQoXtLkhIBn3fbuk6FgAP+ctWeBsWVTM+R/bThvUZN+ww==",
      "requires": {
        "format-util": "1.0.3"
      }
@@ -190,9 +195,9 @@
      "integrity": "sha512-RNC5tX/JMRYR+qVdJTEAWnRxw0Yf9lvbO8lTuAOvgDODkiA8lveTSkvrNMhmaGKEyimJpJl+myb/syVS9YyPuw=="
    },
    "prismjs": {
-      "version": "1.9.0",
-      "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.9.0.tgz",
-      "integrity": "sha1-+j4tntw8OIfB8fMJXUHx+bQgDw8=",
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.10.0.tgz",
+      "integrity": "sha1-d+UYfCrmsyU/zDEwKc8l/lN3hyE=",
      "requires": {
        "clipboard": "1.7.1"
      }
@@ -217,9 +222,9 @@
      }
    },
    "redoc": {
-      "version": "1.19.3",
-      "resolved": "https://registry.npmjs.org/redoc/-/redoc-1.19.3.tgz",
-      "integrity": "sha1-DfPx+6S92G/+nGIAEzBxUjytVec=",
+      "version": "1.20.0",
+      "resolved": "https://registry.npmjs.org/redoc/-/redoc-1.20.0.tgz",
+      "integrity": "sha1-1c16xoQKJ8/7RzvSiYAFUq+CHq8=",
      "requires": {
        "core-js": "2.5.3",
        "dropkickjs": "2.1.10",
@@ -228,21 +233,16 @@
        "json-pointer": "0.6.0",
        "json-schema-ref-parser": "3.3.1",
        "lunr": "1.0.0",
-        "mark.js": "github:julmot/mark.js#714c9523feca999267f1758da8cfd92d077105d0",
+        "mark.js": "8.11.1",
        "openapi-sampler": "0.4.3",
        "perfect-scrollbar": "0.8.1",
-        "prismjs": "1.9.0",
+        "prismjs": "1.10.0",
        "remarkable": "1.7.1",
        "scrollparent": "2.0.1",
-        "slugify": "1.2.6",
-        "stream-http": "2.7.2",
+        "slugify": "1.2.9",
+        "stream-http": "2.8.0",
        "ts-helpers": "1.1.2",
-        "zone.js": "0.8.18"
-      },
-      "dependencies": {
-        "mark.js": {
-          "version": "github:julmot/mark.js#714c9523feca999267f1758da8cfd92d077105d0"
-        }
+        "zone.js": "0.8.20"
      }
    },
    "remarkable": {
@@ -282,9 +282,9 @@
      "optional": true
    },
    "slugify": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/slugify/-/slugify-1.2.6.tgz",
-      "integrity": "sha512-796YAGnzEnLKQHAFf7H2q1nsjY/9qywSnF9ZkMUbs9he4aZaXO/zFUow0LZ95sBAiQjOX1EmGl23gTYaswiNaQ=="
+      "version": "1.2.9",
+      "resolved": "https://registry.npmjs.org/slugify/-/slugify-1.2.9.tgz",
+      "integrity": "sha512-n0cdJ+kN3slJu8SbZXt/EHjljBqF6MxvMGSg/NPpBzoY7yyXoH38wp/ox20a1JaG1KgmdTN5Lf3aS9+xB2Y2aQ=="
    },
    "sprintf-js": {
      "version": "1.0.3",
@@ -292,9 +292,9 @@
      "integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw="
    },
    "stream-http": {
-      "version": "2.7.2",
-      "resolved": "https://registry.npmjs.org/stream-http/-/stream-http-2.7.2.tgz",
-      "integrity": "sha512-c0yTD2rbQzXtSsFSVhtpvY/vS6u066PcXOX9kBB3mSO76RiUQzL340uJkGBWnlBg4/HZzqiUXtaVA7wcRcJgEw==",
+      "version": "2.8.0",
+      "resolved": "https://registry.npmjs.org/stream-http/-/stream-http-2.8.0.tgz",
+      "integrity": "sha512-sZOFxI/5xw058XIRHl4dU3dZ+TTOIGJR78Dvo0oEAejIt4ou27k+3ne1zYmCV+v7UucbxIFQuOgnkTVHh8YPnw==",
      "requires": {
        "builtin-status-codes": "3.0.0",
        "inherits": "2.0.3",
@@ -312,9 +312,9 @@
      }
    },
    "swagger-ui-dist": {
-      "version": "3.9.0",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.9.0.tgz",
-      "integrity": "sha1-eWXZZ6ds74tFWo0M2ROA/2Ss2RM="
+      "version": "3.9.2",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.9.2.tgz",
+      "integrity": "sha1-XuK7G2IFPC3ydGnlVZDGX8AOidQ="
    },
    "tiny-emitter": {
      "version": "2.0.2",
@@ -362,16 +362,16 @@
      "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-3.19.0.tgz",
      "integrity": "sha512-V94f3ODuluBS4kQLLjNhwoMek0dyIXCsvNu/A17dAyJ6sMhT5KkJQwSn07R0naByLIXJWMDk+ruMfI/3G3hS4Q==",
      "requires": {
-        "commander": "2.12.2",
+        "commander": "2.13.0",
        "lodash.get": "4.4.2",
        "lodash.isequal": "4.5.0",
        "validator": "9.2.0"
      }
    },
    "zone.js": {
-      "version": "0.8.18",
-      "resolved": "https://registry.npmjs.org/zone.js/-/zone.js-0.8.18.tgz",
-      "integrity": "sha512-knKOBQM0oea3/x9pdyDuDi7RhxDlJhOIkeixXSiTKWLgs4LpK37iBc+1HaHwzlciHUKT172CymJFKo8Xgh+44Q=="
+      "version": "0.8.20",
+      "resolved": "https://registry.npmjs.org/zone.js/-/zone.js-0.8.20.tgz",
+      "integrity": "sha512-FXlA37ErSXCMy5RNBcGFgCI/Zivqzr0D19GuvDxhcYIJc7xkFp6c29DKyODJu0Zo+EMyur/WPPgcBh1EHjB9jA=="
    }
  }
 }
@@ -1,7 +1,7 @@
 {
  "name": "drf-yasg",
  "dependencies": {
-    "redoc": "^1.19.3",
-    "swagger-ui-dist": "^3.9.0"
+    "redoc": "^1.20.0",
+    "swagger-ui-dist": "^3.9.2"
  }
 }
@@ -7,6 +7,6 @@ future>=0.16.0
 six>=1.11.0
 uritemplate>=3.0.0

-djangorestframework>=3.7.0
+djangorestframework>=3.7.7
 Django>=1.11.7,<2.0; python_version <= "2.7"
 Django>=1.11.7; python_version >= "3.4"
@@ -31,6 +31,7 @@ SWAGGER_DEFAULTS = {
            'type': 'basic'
        }
    },
+    'SECURITY_REQUIREMENTS': None,
    'LOGIN_URL': getattr(settings, 'LOGIN_URL', None),
    'LOGOUT_URL': getattr(settings, 'LOGOUT_URL', None),
    'VALIDATOR_URL': '',
@@ -8,7 +8,6 @@ from coreapi.compat import force_bytes
 from ruamel import yaml

 from . import openapi
-from .app_settings import swagger_settings
 from .errors import SwaggerValidationError


@@ -94,7 +93,6 @@ class _OpenAPICodec(object):
        :return: swagger spec as dict
        :rtype: OrderedDict
        """
-        swagger.security_definitions = swagger_settings.SECURITY_DEFINITIONS
        return swagger.as_odict()


@@ -10,13 +10,14 @@ from rest_framework.compat import URLPattern, URLResolver, get_original_route
 from rest_framework.schemas.generators import EndpointEnumerator as _EndpointEnumerator
 from rest_framework.schemas.generators import SchemaGenerator, endpoint_ordering
 from rest_framework.schemas.inspectors import get_pk_description
-
-from drf_yasg.errors import SwaggerGenerationError
+from rest_framework.settings import api_settings as rest_framework_settings

 from . import openapi
 from .app_settings import swagger_settings
+from .errors import SwaggerGenerationError
 from .inspectors.field import get_basic_type_info, get_queryset_field
 from .openapi import ReferenceResolver
+from .utils import get_consumes, get_produces

 logger = logging.getLogger(__name__)

@@ -30,7 +31,8 @@ class EndpointEnumerator(_EndpointEnumerator):

    def get_path_from_regex(self, path_regex):
        if path_regex.endswith(')'):
-            logger.warning("url pattern does not end in $ ('%s') - unexpected things might happen")
+            logger.warning("url pattern does not end in $ ('%s') - unexpected things might happen",
+                           path_regex)
        return self.unescape_path(super(EndpointEnumerator, self).get_path_from_regex(path_regex))

    def should_include_endpoint(self, path, callback, app_name='', namespace='', url_name=None):
@@ -43,6 +45,9 @@ class EndpointEnumerator(_EndpointEnumerator):
            if version and version not in namespace.split(':'):
                return False

+        if getattr(callback.cls, 'swagger_schema', object()) is None:
+            return False
+
        return True

    def replace_version(self, path, callback):
@@ -97,6 +102,8 @@ class EndpointEnumerator(_EndpointEnumerator):
                    namespace="%s:%s" % (namespace, pattern.namespace) if namespace else pattern.namespace
                )
                api_endpoints.extend(nested_endpoints)
+            else:
+                logger.warning("unknown pattern type {}".format(type(pattern)))

        api_endpoints = sorted(api_endpoints, key=endpoint_ordering)

@@ -162,6 +169,9 @@ class OpenAPISchemaGenerator(object):
        self._gen = SchemaGenerator(info.title, url, info.get('description', ''), patterns, urlconf)
        self.info = info
        self.version = version
+        self.consumes = []
+        self.produces = []
+
        if url is None and swagger_settings.DEFAULT_API_URL is not None:
            url = swagger_settings.DEFAULT_API_URL

@@ -188,14 +198,22 @@ class OpenAPISchemaGenerator(object):
        """
        endpoints = self.get_endpoints(request)
        components = ReferenceResolver(openapi.SCHEMA_DEFINITIONS)
+        self.consumes = get_consumes(rest_framework_settings.DEFAULT_PARSER_CLASSES)
+        self.produces = get_produces(rest_framework_settings.DEFAULT_RENDERER_CLASSES)
        paths, prefix = self.get_paths(endpoints, components, request, public)

+        security_definitions = swagger_settings.SECURITY_DEFINITIONS
+        security_requirements = swagger_settings.SECURITY_REQUIREMENTS
+        if security_requirements is None:
+            security_requirements = [{security_scheme: [] for security_scheme in swagger_settings.SECURITY_DEFINITIONS}]
+
        url = self.url
        if url is None and request is not None:
            url = request.build_absolute_uri()

        return openapi.Swagger(
-            info=self.info, paths=paths,
+            info=self.info, paths=paths, consumes=self.consumes or None, produces=self.produces or None,
+            security_definitions=security_definitions, security=security_requirements,
            _url=url, _prefix=prefix, _version=self.version, **dict(components)
        )

@@ -321,7 +339,6 @@ class OpenAPISchemaGenerator(object):
        :param Request request: the request made against the schema view; can be None
        :rtype: openapi.Operation
        """
-
        operation_keys = self.get_operation_keys(path[len(prefix):], method, view)
        overrides = self.get_overrides(view, method)

@@ -333,8 +350,16 @@ class OpenAPISchemaGenerator(object):
        #   3. on the swagger_auto_schema decorator
        view_inspector_cls = overrides.get('auto_schema', view_inspector_cls)

+        if view_inspector_cls is None:
+            return None
+
        view_inspector = view_inspector_cls(view, path, method, components, request, overrides)
-        return view_inspector.get_operation(operation_keys)
+        operation = view_inspector.get_operation(operation_keys)
+        if set(operation.consumes) == set(self.consumes):
+            del operation.consumes
+        if set(operation.produces) == set(self.produces):
+            del operation.produces
+        return operation

    def get_path_item(self, path, view_cls, operations):
        """Get a :class:`.PathItem` object that describes the parameters and operations related to a single path in the
@@ -6,7 +6,10 @@ from rest_framework.status import is_success

 from .. import openapi
 from ..errors import SwaggerGenerationError
-from ..utils import force_serializer_instance, guess_response_status, is_list_view, no_body, param_list_to_odict
+from ..utils import (
+    force_serializer_instance, get_consumes, get_produces, guess_response_status, is_list_view, no_body,
+    param_list_to_odict
+)
 from .base import ViewInspector


@@ -18,6 +21,7 @@ class SwaggerAutoSchema(ViewInspector):

    def get_operation(self, operation_keys):
        consumes = self.get_consumes()
+        produces = self.get_produces()

        body = self.get_request_body_parameters(consumes)
        query = self.get_query_parameters()
@@ -27,6 +31,8 @@ class SwaggerAutoSchema(ViewInspector):

        operation_id = self.get_operation_id(operation_keys)
        description = self.get_description()
+        security = self.get_security()
+        assert security is None or isinstance(security, list), "security must be a list of securiy requirement objects"
        tags = self.get_tags(operation_keys)

        responses = self.get_responses()
@@ -37,7 +43,9 @@ class SwaggerAutoSchema(ViewInspector):
            responses=responses,
            parameters=parameters,
            consumes=consumes,
+            produces=produces,
            tags=tags,
+            security=security
        )

    def get_request_body_parameters(self, consumes):
@@ -88,8 +96,8 @@ class SwaggerAutoSchema(ViewInspector):
            if body_override is no_body:
                return None
            if self.method not in self.body_methods:
-                raise SwaggerGenerationError("request_body can only be applied to PUT, PATCH or POST views; "
-                                             "are you looking for query_serializer or manual_parameters?")
+                raise SwaggerGenerationError("request_body can only be applied to (" + ','.join(self.body_methods) +
+                                             "); are you looking for query_serializer or manual_parameters?")
            if isinstance(body_override, openapi.Schema.OR_REF):
                return body_override
            return force_serializer_instance(body_override)
@@ -286,6 +294,16 @@ class SwaggerAutoSchema(ViewInspector):
            description = self._sch.get_description(self.path, self.method)
        return description

+    def get_security(self):
+        """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.
+
+        :return: security requirements
+        :rtype: list[dict[str,list[str]]]"""
+        return self.overrides.get('security', None)
+
    def get_tags(self, operation_keys):
        """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.
@@ -301,7 +319,11 @@ class SwaggerAutoSchema(ViewInspector):

        :rtype: list[str]
        """
-        media_types = [parser.media_type for parser in getattr(self.view, 'parser_classes', [])]
-        if all(is_form_media_type(encoding) for encoding in media_types):
-            return media_types
-        return media_types[:1]
+        return get_consumes(getattr(self.view, 'parser_classes', []))
+
+    def get_produces(self):
+        """Return the MIME types this endpoint can produce.
+
+        :rtype: list[str]
+        """
+        return get_produces(getattr(self.view, 'renderer_classes', []))
@@ -211,7 +211,8 @@ class Info(SwaggerDict):


 class Swagger(SwaggerDict):
-    def __init__(self, info=None, _url=None, _prefix=None, _version=None, paths=None, definitions=None, **extra):
+    def __init__(self, info=None, _url=None, _prefix=None, _version=None, consumes=None, produces=None,
+                 security_definitions=None, security=None, paths=None, definitions=None, **extra):
        """Root Swagger object.

        :param .Info info: info object
@@ -219,6 +220,10 @@ class Swagger(SwaggerDict):
        :param str _prefix: 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
        :param str _version: version string to override Info
+        :param list[dict] security_definitions: list of supported authentication mechanisms
+        :param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation
+        :param list[str] consumes: consumed MIME types; can be overriden in Operation
+        :param list[str] produces: produced MIME types; can be overriden in Operation
        :param .Paths paths: paths object
        :param dict[str,.Schema] definitions: named models
        """
@@ -234,6 +239,10 @@ class Swagger(SwaggerDict):
            self.schemes = [url.scheme]

        self.base_path = self.get_base_path(get_script_prefix(), _prefix)
+        self.consumes = consumes
+        self.produces = produces
+        self.security_definitions = filter_none(security_definitions)
+        self.security = filter_none(security)
        self.paths = paths
        self.definitions = filter_none(definitions)
        self._insert_extras__()
@@ -304,8 +313,8 @@ class PathItem(SwaggerDict):


 class Operation(SwaggerDict):
-    def __init__(self, operation_id, responses, parameters=None, consumes=None,
-                 produces=None, summary=None, description=None, tags=None, **extra):
+    def __init__(self, operation_id, responses, parameters=None, consumes=None, produces=None, summary=None,
+                 description=None, tags=None, security=None, **extra):
        """Information about an API operation (path + http method combination)

        :param str operation_id: operation ID, should be unique across all operations
@@ -316,6 +325,7 @@ class Operation(SwaggerDict):
        :param str summary: operation summary; should be < 120 characters
        :param str description: operation description; can be of any length and supports markdown
        :param list[str] tags: operation tags
+        :param list[dict[str,list[str]]] security: list of security requirements
        """
        super(Operation, self).__init__(**extra)
        self.operation_id = operation_id
@@ -326,6 +336,7 @@ class Operation(SwaggerDict):
        self.consumes = filter_none(consumes)
        self.produces = filter_none(produces)
        self.tags = filter_none(tags)
+        self.security = filter_none(security)
        self._insert_extras__()


@@ -4,6 +4,7 @@ from collections import OrderedDict

 from rest_framework import serializers, status
 from rest_framework.mixins import DestroyModelMixin, RetrieveModelMixin, UpdateModelMixin
+from rest_framework.request import is_form_media_type
 from rest_framework.views import APIView

 logger = logging.getLogger(__name__)
@@ -11,10 +12,12 @@ logger = logging.getLogger(__name__)
 #: used to forcibly remove the body of a request via :func:`.swagger_auto_schema`
 no_body = object()

+unset = object()

-def swagger_auto_schema(method=None, methods=None, auto_schema=None, request_body=None, query_serializer=None,
-                        manual_parameters=None, operation_id=None, operation_description=None, responses=None,
-                        field_inspectors=None, filter_inspectors=None, paginator_inspectors=None,
+
+def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_body=None, query_serializer=None,
+                        manual_parameters=None, operation_id=None, operation_description=None, security=None,
+                        responses=None, field_inspectors=None, filter_inspectors=None, paginator_inspectors=None,
                        **extra_overrides):
    """Decorate a view method to customize the :class:`.Operation` object generated from it.

@@ -23,17 +26,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=None, request_bod

    The `auto_schema` and `operation_description` arguments take precendence over view- or method-level values.

-    .. versionchanged:: 1.1
-       Added the ``extra_overrides`` and ``operatiod_id`` parameters.
-
-    .. versionchanged:: 1.1
-       Added the ``field_inspectors``, ``filter_inspectors`` and ``paginator_inspectors`` parameters.
-
    :param str method: for multi-method views, the http method the options should apply to
    :param list[str] methods: for multi-method views, the http methods the options should apply to
    :param .inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object;
        this overrides both the class-level ``swagger_schema`` attribute and the ``DEFAULT_AUTO_SCHEMA_CLASS``
-        setting
+        setting, and can be set to ``None`` to prevent this operation from being generated
    :param .Schema,.SchemaRef,.Serializer request_body: custom request body, or :data:`.no_body`. The value given here
        will be used as the ``schema`` property of a :class:`.Parameter` with ``in: 'body'``.

@@ -62,6 +59,9 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=None, request_bod

    :param str operation_id: operation ID override; the operation ID must be unique accross the whole API
    :param str operation_description: operation description override
+    :param str security: 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
    :param dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: 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 any ``2xx`` response is given the automatic response is
@@ -88,18 +88,20 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=None, request_bod
    def decorator(view_method):
        assert not any(hm in extra_overrides for hm in APIView.http_method_names), "HTTP method names not allowed here"
        data = {
-            'auto_schema': auto_schema,
            'request_body': request_body,
            'query_serializer': query_serializer,
            'manual_parameters': manual_parameters,
            'operation_id': operation_id,
            'operation_description': operation_description,
+            'security': security,
            'responses': responses,
            'filter_inspectors': list(filter_inspectors) if filter_inspectors else None,
            'paginator_inspectors': list(paginator_inspectors) if paginator_inspectors else None,
            'field_inspectors': list(field_inspectors) if field_inspectors else None,
        }
        data = filter_none(data)
+        if auto_schema is not unset:
+            data['auto_schema'] = auto_schema
        data.update(extra_overrides)
        if not data:  # pragma: no cover
            # no overrides to set, no use in doing more work
@@ -244,3 +246,30 @@ def force_serializer_instance(serializer):
    assert isinstance(serializer, serializers.BaseSerializer), \
        "Serializer class or instance required, not %s" % type(serializer).__name__
    return serializer
+
+
+def get_consumes(parser_classes):
+    """Extract ``consumes`` MIME types from a list of parser classes.
+
+    :param list parser_classes: parser classes
+    :return: MIME types for ``consumes``
+    :rtype: list[str]
+    """
+    media_types = [parser.media_type for parser in parser_classes or []]
+    if all(is_form_media_type(encoding) for encoding in media_types):
+        return media_types
+    else:
+        media_types = [encoding for encoding in media_types if not is_form_media_type(encoding)]
+        return media_types
+
+
+def get_produces(renderer_classes):
+    """Extract ``produces`` MIME types from a list of renderer classes.
+
+    :param list renderer_classes: renderer classes
+    :return: MIME types for ``produces``
+    :rtype: list[str]
+    """
+    media_types = [renderer.media_type for renderer in renderer_classes or []]
+    media_types = [encoding for encoding in media_types if 'html' not in encoding]
+    return media_types
@@ -2,6 +2,7 @@ from djangorestframework_camel_case.parser import CamelCaseJSONParser
 from djangorestframework_camel_case.render import CamelCaseJSONRenderer
 from inflection import camelize
 from rest_framework import generics
+from rest_framework.parsers import FormParser

 from drf_yasg import openapi
 from drf_yasg.inspectors import SwaggerAutoSchema
@@ -21,7 +22,7 @@ class SnippetList(generics.ListCreateAPIView):
    queryset = Snippet.objects.all()
    serializer_class = SnippetSerializer

-    parser_classes = (CamelCaseJSONParser,)
+    parser_classes = (FormParser, CamelCaseJSONParser,)
    renderer_classes = (CamelCaseJSONRenderer,)
    swagger_schema = CamelCaseOperationIDAutoSchema

@@ -19,13 +19,17 @@ class UserList(APIView):
        serializer = UserSerializerrr(queryset, many=True)
        return Response(serializer.data)

-    @swagger_auto_schema(operation_description="apiview post description override", request_body=openapi.Schema(
-        type=openapi.TYPE_OBJECT,
-        required=['username'],
-        properties={
-            'username': openapi.Schema(type=openapi.TYPE_STRING)
-        },
-    ))
+    @swagger_auto_schema(
+        operation_description="apiview post description override",
+        request_body=openapi.Schema(
+            type=openapi.TYPE_OBJECT,
+            required=['username'],
+            properties={
+                'username': openapi.Schema(type=openapi.TYPE_STRING)
+            },
+        ),
+        security=[]
+    )
    def post(self, request):
        serializer = UserSerializerrr(request.data)
        serializer.is_valid(raise_exception=True)
@@ -16,6 +16,15 @@ host: test.local:8002
 schemes:
  - http
 basePath: /
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  basic:
+    type: basic
+security:
+  - basic: []
 paths:
  /articles/:
    get:
@@ -63,8 +72,6 @@ paths:
                type: array
                items:
                  $ref: '#/definitions/Article'
-      consumes:
-        - application/json
      tags:
        - articles
    post:
@@ -81,8 +88,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Article'
-      consumes:
-        - application/json
      tags:
        - articles
    parameters: []
@@ -108,8 +113,6 @@ paths:
            type: array
            items:
              $ref: '#/definitions/Article'
-      consumes:
-        - application/json
      tags:
        - articles
    parameters: []
@@ -123,8 +126,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Article'
-      consumes:
-        - application/json
      tags:
        - articles
    put:
@@ -141,8 +142,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Article'
-      consumes:
-        - application/json
      tags:
        - articles
    patch:
@@ -161,8 +160,6 @@ paths:
            $ref: '#/definitions/Article'
        '404':
          description: slug not found
-      consumes:
-        - application/json
      tags:
        - articles
    delete:
@@ -172,8 +169,6 @@ paths:
      responses:
        '204':
          description: ''
-      consumes:
-        - application/json
      tags:
        - articles
    parameters:
@@ -246,8 +241,6 @@ paths:
      responses:
        '200':
          description: ''
-      consumes:
-        - application/json
      tags:
        - plain
    parameters: []
@@ -263,8 +256,6 @@ paths:
            type: array
            items:
              $ref: '#/definitions/Snippet'
-      consumes:
-        - application/json
      tags:
        - snippets
    post:
@@ -281,8 +272,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Snippet'
-      consumes:
-        - application/json
      tags:
        - snippets
    parameters: []
@@ -296,8 +285,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Snippet'
-      consumes:
-        - application/json
      tags:
        - snippets
    put:
@@ -314,8 +301,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Snippet'
-      consumes:
-        - application/json
      tags:
        - snippets
    patch:
@@ -332,8 +317,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/Snippet'
-      consumes:
-        - application/json
      tags:
        - snippets
    delete:
@@ -348,8 +331,6 @@ paths:
      responses:
        '204':
          description: ''
-      consumes:
-        - application/json
      tags:
        - snippets
    parameters:
@@ -380,8 +361,6 @@ paths:
            type: array
            items:
              $ref: '#/definitions/UserSerializerrr'
-      consumes:
-        - application/json
      tags:
        - users
    post:
@@ -408,10 +387,9 @@ paths:
            properties:
              username:
                type: string
-      consumes:
-        - application/json
      tags:
        - users
+      security: []
    patch:
      operationId: users_dummy
      description: dummy operation
@@ -419,8 +397,6 @@ paths:
      responses:
        '200':
          description: ''
-      consumes:
-        - application/json
      tags:
        - users
    parameters: []
@@ -438,8 +414,6 @@ paths:
          description: response description
          schema:
            $ref: '#/definitions/UserSerializerrr'
-      consumes:
-        - application/json
      tags:
        - users
    put:
@@ -456,8 +430,6 @@ paths:
          description: ''
          schema:
            $ref: '#/definitions/UserSerializerrr'
-      consumes:
-        - application/json
      tags:
        - users
    parameters:
@@ -1120,6 +1092,3 @@ definitions:
          pattern: ^[-a-zA-Z0-9_]+$
        readOnly: true
        uniqueItems: true
-securityDefinitions:
-  basic:
-    type: basic
@@ -67,3 +67,15 @@ def test_no_netloc(mock_schema_request):
    swagger = generator.get_schema(mock_schema_request, public=True)
    assert 'host' not in swagger and 'schemes' not in swagger
    assert swagger['info']['version'] == 'v2'
+
+
+def test_securiy_requirements(swagger_settings, mock_schema_request):
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title="Test generator", default_version="v1"),
+        version="v2",
+        url='',
+    )
+    swagger_settings['SECURITY_REQUIREMENTS'] = []
+
+    swagger = generator.get_schema(mock_schema_request, public=True)
+    assert swagger['security'] == []
@@ -15,7 +15,7 @@ deps =
    django111: Django>=1.11,<2.0
    django20: Django>=2.0,<2.1

-    drf37: djangorestframework>=3.7.3,<3.8
+    drf37: djangorestframework>=3.7.7,<3.8

    # test with the latest build of Django and django-rest-framework to get early warning of compatibility issues
    drfmaster: https://github.com/encode/django-rest-framework/archive/master.tar.gz
@@ -1,10 +1,8 @@
 #!/bin/bash
 set -ev
 npm update
-npm install -g --prefix ./node_modules/redoc-alpha redoc@latest

 cp node_modules/redoc/dist/redoc.min.js src/drf_yasg/static/drf-yasg/redoc/
-cp node_modules/redoc-alpha/node_modules/redoc/bundles/redoc.standalone.js src/drf_yasg/static/drf-yasg/redoc-alpha/
 cp -r node_modules/swagger-ui-dist src/drf_yasg/static/drf-yasg/
 pushd src/drf_yasg/static/drf-yasg/swagger-ui-dist/ >/dev/null
 rm -f package.json .npmignore README.md
Author	SHA1	Message	Date
Cristi Vîjdea	05901e99aa	Add 1.3.1 changelog	2018-01-24 17:43:38 +02:00
Cristi Vîjdea	a211184478	Add documentation about excluding endpoints Closes #50.	2018-01-24 17:38:10 +02:00
Cristi Vîjdea	a3e81ef7f6	Improve handling of consumes and produces attributes (#55 ) * Fix get_consumes * Generate produces for Operation * Set global consumes and produces from rest framework DEFAULT_ settings	2018-01-24 14:44:00 +02:00
Cristi Vîjdea	a46b684fea	Add 1.3.0 changelog	2018-01-23 12:44:16 +02:00
Cristi Vîjdea	fc35d9043e	Add security requirements handling (#54 ) * Add security requirements handling * Update swagger-ui to 3.9.2, ReDoc to 1.20.0 Closes #39.	2018-01-23 12:43:25 +02:00
Cristi Vîjdea	f18ff60ae7	Update swagger-ui to 3.9.1	2018-01-19 18:37:44 +01:00
Daniel Hahler	a82730d32b	Fix logging message in get_path_from_regex (#49 ) Adds the missing param.	2018-01-17 21:49:22 +01:00
Cristi Vîjdea	e30af0287f	Fix README and CONTRIBUTING	2018-01-12 15:18:18 +01:00
Cristi Vîjdea	fc253665dd	Release 1.2.2	2018-01-12 09:44:42 +01:00
h-hirokawa	33199aec59	Update the minimum required version of DRF to 3.7.7 Closes #44, #45.	2018-01-12 09:40:26 +01:00
Cristi Vîjdea	9d1150f1ab	Fix travis deployment	2018-01-12 04:38:30 +01:00
Cristi Vîjdea	bc4037f721	Fix coverage problems	2018-01-12 04:36:04 +01:00