fix #559: recursively resolve type of one2one using target_field

* Add example for using swagger_schema_fields for a Field
* Mention that Meta class can be added to fields as well
* Reference the DRF docs on how to add validation to serializers

.codecov.yml

@@ -11,15 +11,15 @@ coverage:
       default:
         enabled: yes
         target: auto
-        threshold: 0%
+        threshold: 100%
         if_no_uploads: error
         if_ci_failed: error
 
     patch:
       default:
         enabled: yes
-        target: 80%
-        threshold: 0%
+        target: 100%
+        threshold: 100%
         if_no_uploads: error
         if_ci_failed: error
 

.coveragerc

@@ -1,6 +1,8 @@
 [run]
 source = drf_yasg
 branch = True
+parallel = true
+disable_warnings = module-not-measured
 
 [report]
 # Regexes for lines to exclude from consideration
@@ -14,9 +16,15 @@ exclude_lines =
 
     # Don't complain if tests don't hit defensive assertion code:
     raise AssertionError
+    raise ImproperlyConfigured
     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:
     if 0:
@@ -26,7 +34,8 @@ exclude_lines =
     raise SwaggerGenerationError
 
 ignore_errors = True
-precision = 0
+precision = 2
+show_missing = True
 
 [paths]
 source =

.gitignore

@@ -1,4 +1,9 @@
 node_modules/
+testproj/db.sqlite3
+testproj/staticfiles
+\.pytest_cache/
+docs/\.doctrees/
+pip-wheel-metadata/
 
 # Created by .ignore support plugin (hsz.mobi)
 ### Python template

.idea/codeStyles/Project.xml

@@ -0,0 +1,7 @@
+<component name="ProjectCodeStyleConfiguration">
+  <code_scheme name="Project" version="173">
+    <codeStyleSettings language="Python">
+      <option name="SOFT_MARGINS" value="120" />
+    </codeStyleSettings>
+  </code_scheme>
+</component>

.idea/codeStyles/codeStyleConfig.xml

@@ -0,0 +1,5 @@
+<component name="ProjectCodeStyleConfiguration">
+  <state>
+    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
+  </state>
+</component>

.idea/drf-yasg.iml

@@ -4,32 +4,45 @@
     <facet type="django" name="Django">
       <configuration>
         <option name="rootFolder" value="$MODULE_DIR$/testproj" />
-        <option name="settingsModule" value="testproj/settings.py" />
+        <option name="settingsModule" value="testproj/settings/local.py" />
         <option name="manageScript" value="manage.py" />
         <option name="environment" value="&lt;map/&gt;" />
         <option name="doNotUseTestRunner" value="false" />
+        <option name="trackFilePattern" value="migrations" />
       </configuration>
     </facet>
   </component>
   <component name="NewModuleRootManager">
     <content url="file://$MODULE_DIR$">
-      <sourceFolder url="file://$MODULE_DIR$" isTestSource="false" />
       <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
       <sourceFolder url="file://$MODULE_DIR$/testproj" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.cache" />
+      <excludeFolder url="file://$MODULE_DIR$/.eggs" />
+      <excludeFolder url="file://$MODULE_DIR$/.pytest_cache" />
+      <excludeFolder url="file://$MODULE_DIR$/.tox" />
+      <excludeFolder url="file://$MODULE_DIR$/build" />
+      <excludeFolder url="file://$MODULE_DIR$/dist" />
+      <excludeFolder url="file://$MODULE_DIR$/docs/.doctrees" />
+      <excludeFolder url="file://$MODULE_DIR$/docs/_build" />
+      <excludeFolder url="file://$MODULE_DIR$/htmlcov" />
+      <excludeFolder url="file://$MODULE_DIR$/src/drf_yasg.egg-info" />
+      <excludeFolder url="file://$MODULE_DIR$/venv" />
     </content>
-    <orderEntry type="jdk" jdkName="Python 3.6 (drf-yasg)" jdkType="Python SDK" />
+    <orderEntry type="jdk" jdkName="Python 3 (drf-yasg)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" name="immutable" level="application" />
   </component>
   <component name="TemplatesService">
     <option name="TEMPLATE_CONFIGURATION" value="Django" />
     <option name="TEMPLATE_FOLDERS">
       <list>
-        <option value="$MODULE_DIR$/drf_yasg/templates" />
+        <option value="$MODULE_DIR$/src/drf_yasg/templates" />
+        <option value="$MODULE_DIR$/testproj/testproj/templates" />
       </list>
     </option>
   </component>
   <component name="TestRunnerService">
-    <option name="projectConfiguration" value="py.test" />
-    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+    <option name="projectConfiguration" value="pytest" />
+    <option name="PROJECT_TEST_RUNNER" value="pytest" />
   </component>
 </module>

.idea/encodings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding" addBOMForNewFiles="with NO BOM" />
+</project>

.idea/inspectionProfiles/Project_Default.xml

@@ -10,11 +10,12 @@
     <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
       <option name="ourVersions">
         <value>
-          <list size="4">
+          <list size="5">
             <item index="0" class="java.lang.String" itemvalue="2.7" />
             <item index="1" class="java.lang.String" itemvalue="3.4" />
             <item index="2" class="java.lang.String" itemvalue="3.5" />
             <item index="3" class="java.lang.String" itemvalue="3.6" />
+            <item index="4" class="java.lang.String" itemvalue="3.7" />
           </list>
         </value>
       </option>
@@ -54,11 +55,6 @@
       </option>
     </inspection_tool>
     <inspection_tool class="PyShadowingNamesInspection" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
-    <inspection_tool class="PyUnusedLocalInspection" enabled="false" level="WEAK WARNING" enabled_by_default="false">
-      <option name="ignoreTupleUnpacking" value="true" />
-      <option name="ignoreLambdaParameters" value="true" />
-      <option name="ignoreLoopIterationVariables" value="true" />
-    </inspection_tool>
     <inspection_tool class="SpellCheckingInspection" enabled="false" level="TYPO" enabled_by_default="false">
       <option name="processCode" value="true" />
       <option name="processLiterals" value="true" />

.idea/jsLibraryMappings.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptLibraryMappings">
+    <file url="file://$PROJECT_DIR$" libraries="{immutable}" />
+  </component>
+</project>

.idea/misc.xml

@@ -69,5 +69,8 @@
       <textMaps />
     </LinkMapSettings>
   </component>
-  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.6 (drf-yasg)" project-jdk-type="Python SDK" />
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3 (drf-yasg)" project-jdk-type="Python SDK" />
+  <component name="PythonCompatibilityInspectionAdvertiser">
+    <option name="version" value="3" />
+  </component>
 </project>

.readthedocs.yml

@@ -0,0 +1,15 @@
+requirements_file: requirements/docs.txt
+
+build:
+  image: latest
+
+python:
+  version: 3.6
+  setup_py_install: false
+  pip_install: true  # need this for correct pyproject.toml handling
+  extra_requirements:
+    - validation
+
+# extra formats in addition to the default HTML web docs
+formats:
+    - pdf

.travis.yml

@@ -1,45 +1,67 @@
 language: python
-cache: pip
 python:
- - '2.7'
- - '3.4'
- - '3.5'
- - '3.6'
- - '3.7-dev'
+  - '3.6'
+  - '3.7'
+  - '3.8'
 
-env:
- - DRF=3.7
+dist: xenial
+
+cache: pip
 
 matrix:
-  fast_finish: true
   include:
-    - python: '3.5'
-      env: TOXENV=docs
-    - python: '2.7'
-      env: TOXENV=flake8
     - python: '3.6'
-      env: DRF=master
+      env: TOXENV=docs
+    - python: '3.7'
+      env: TOXENV=djmaster
+    - python: '3.7'
+      env: TOXENV=lint
+
+    - stage: publish
+      python: '3.6'
+      before_script:
+        # workaround for Travis' inability to build PEP517 projects; anything added to build-system.requires
+        # will also have to be added here until Travis implements this
+        - pip install setuptools-scm
+      script: skip
+      env: PYPI_DEPLOY=true
+      deploy: &pypi
+        provider: pypi
+        user: cvijdea
+        password:
+          secure: 54DvknusZ7uHlo9IJxgbNDVKYrwaScyuOZyAGZPb/PTUj8WroQZtp1bFOrAtzfcM4ctIIoLWVzmSwrxypmU4hNif2ZvJ8Vo2PnVh9G6wQ2fD2FN+kFBYczBNrzW5xhjJ53OiTYy/zzHgzxC/sp+hB4sibWl0v69PGU5v6oyBltOWZLXYpqMA6fINt62XDVwuNHVKAo1T/yoeJMQKeCKYAx8QOtve9/qcl5Td/OOM6z42hX5+q3N7RgkCFLl0KopwaPwBaL1Z3Bn+aUhiIUdrRrdigY329QtNXoa/VRBNvUSAwbvecShmgl3c9HigL2ZWmtmHaXda6YCdqmbVfSHSEDsn4AwhZ3A9WblbRtuBwP79YKiE+4BLmgLlGGA4IrAKr3woe+078q/bGqBzmeDd+jt72hhibzD5B96zo4tSNksSxSJGwMYH988fBN/ppynrzRvO0sR/THwpb0r42era8tRd3ZVBefloVas/nQZZs4+zMYoO0fbaLDXdkfaxsF5/X6WkwTYjbI3tdapUT6lYXwi1eKUM1ZGsfKpuq0lFa3qxevYBKveWStQwGyJz1KhVUHbo3OrA3U6q9yoqpzhcZBhzGAPSgumi+EkBUj69cymlYkmqXVBn4VnWsdeFefNYE6Kvh/HJEDPDaWSNgfVLN9xWVqJqM7QiWA351W9dRZA=
+        on:
+          tags: true
+        distributions: "sdist bdist_wheel"
 
   allow_failures:
-    - env: TOXENV=flake8
-    - env: DRF=master
-    - python: '3.7-dev'
+    - env: TOXENV=lint
+    - env: TOXENV=djmaster
+
+  fast_finish: true
 
 install:
- - pip install -r requirements/ci.txt
+  - python -m pip install -U pip setuptools
+  - pip install -r requirements/ci.txt
 
 before_script:
- - coverage erase
+  - coverage erase
 
 script:
- - tox
+  - tox
 
 after_success:
- - codecov
+  - |
+    if [[ -z "$TOXENV" && -z "$PYPI_DEPLOY" ]]; then
+      coverage combine || true
+      coverage report
+      codecov
+    fi
 
-branches:
-  only:
-    - master
+stages:
+  - test
+  - name: publish
+    if: tag IS present
 
 notifications:
   email:

CONTRIBUTING.rst

@@ -6,7 +6,7 @@
 Contributing
 ############
 
-Contributions are always welcome and appreciated! Here are some ways you can contribut.
+Contributions are always welcome and appreciated! Here are some ways you can contribute.
 
 ******
 Issues
@@ -27,43 +27,56 @@ Pull requests
 
 You want to contribute some code? Great! Here are a few steps to get you started:
 
-#. Fork the repository on GitHub
-#. Clone your fork and create a branch for the code you want to add
-#. Create a new virtualenv and install the package in development mode
+#. **Fork the repository on GitHub**
+#. **Clone your fork and create a branch for the code you want to add**
+#. **Create a new virtualenv and install the package in development mode**
 
    .. code:: console
 
       $ virtualenv venv
       $ source venv/bin/activate
-      (venv) $ pip install -e .[validation]
-      (venv) $ pip install -rrequirements/dev.txt -rrequirements/test.txt
+      (venv) $ python -m pip install -U pip setuptools
+      (venv) $ pip install -U -e .[validation]
+      (venv) $ pip install -U -r requirements/dev.txt
 
-#. Make your changes and check them against the test project
+#. **Make your changes and check them against the test project**
 
    .. code:: console
 
       (venv) $ cd testproj
+      (venv) $ python manage.py migrate
       (venv) $ python manage.py runserver
-      (venv) $ curl localhost:8000/swagger.yaml
+      (venv) $ firefox localhost:8000/swagger/
 
-#. Update the tests if necessary
+#. **Update the tests if necessary**
 
    You can find them in the ``tests`` directory.
 
-   If your change modifies the expected schema output, you should download the new generated ``swagger.yaml``, diff it
-   against the old reference output in ``tests/reference.yaml``, and replace it after checking that no unexpected
-   changes appeared.
-
-#. Run tests. The project is setup to use tox and pytest for testing
+   If your change modifies the expected schema output, you should regenerate the reference schema at
+   ``tests/reference.yaml``:
 
    .. code:: console
 
+      (venv) $ python testproj/manage.py generate_swagger tests/reference.yaml --overwrite --user admin --url http://test.local:8002/
+
+   After checking the git diff to verify that no unexpected changes appeared, you should commit the new
+   ``reference.yaml`` together with your changes.
+
+#. **Run tests. The project is setup to use tox and pytest for testing**
+
+   .. code:: console
+
+      # install test dependencies
+      (venv) $ pip install -U -r requirements/test.txt
       # run tests in the current environment, faster than tox
-      (venv) $ pytest --cov
+      (venv) $ pytest -n auto --cov
+      # (optional) sort imports with isort and check flake8 linting
+      (venv) $ isort --apply
+      (venv) $ flake8 src/drf_yasg testproj tests setup.py
       # (optional) run tests for other python versions in separate environments
       (venv) $ tox
 
-#. Update documentation
+#. **Update documentation**
 
    If the change modifies behaviour or adds new features, you should update the documentation and ``README.rst``
    accordingly. Documentation is written in reStructuredText and built using Sphinx. You can find the sources in the
@@ -75,10 +88,33 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
       (venv) $ tox -e docs
 
-#. Push your branch and submit a pull request to the master branch on GitHub
+#. **Push your branch and submit a pull request to the master branch on GitHub**
 
    Incomplete/Work In Progress pull requests are encouraged, because they allow you to get feedback and help more
    easily.
 
-#. Your code must pass all the required travis jobs before it is merged. As of now, this includes running on
-   Python 2.7, 3.4, 3.5 and 3.6, and building the docs succesfully.
+#. **Your code must pass all the required travis jobs before it is merged**
+
+   As of now, this consists of running on Python 2.7, 3.5, 3.6 and 3.7, and building the docs succesfully.
+
+******************
+Maintainer's notes
+******************
+
+Release checklist
+=================
+
+* 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`_
+* 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

LICENSE.rst

@@ -10,7 +10,7 @@ License
 BSD 3-Clause License
 ********************
 
-Copyright (c) 2017, Cristian V. <cristi@cvjd.me> |br|\ All rights reserved.
+Copyright (c) 2017 - 2019, Cristian V. <cristi@cvjd.me> |br|\ All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

MANIFEST.in

@@ -1,5 +1,6 @@
 include README.rst
 include LICENSE.rst
+include pyproject.toml
 recursive-include requirements *
 recursive-include src/drf_yasg/static *
 recursive-include src/drf_yasg/templates *

Procfile

@@ -0,0 +1,2 @@
+release: python testproj/manage.py migrate
+web: gunicorn --chdir testproj testproj.wsgi --log-file -

README.rst

@@ -7,34 +7,49 @@ drf-yasg - Yet another Swagger generator
 
 |travis| |nbsp| |codecov| |nbsp| |rtd-badge| |nbsp| |pypi-version|
 
+|bmac-button|
+
 Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API.
 
 Compatible with
 
-- **Django Rest Framework**: 3.7
-- **Django**: 1.11, 2.0
-- **Python**: 2.7, 3.4, 3.5, 3.6
+- **Django Rest Framework**: 3.8, 3.9, 3.10, 3.11
+- **Django**: 1.11, 2.2, 3.0
+- **Python**: 2.7, 3.6, 3.7, 3.8
 
-**Source**: https://github.com/axnsan12/drf-yasg/
+Only the latest patch version of each ``major.minor`` series of Python, Django and Django REST Framework is supported.
 
-**Documentation**: https://drf-yasg.readthedocs.io/en/latest/
+**Only the latest version of drf-yasg is supported.** Support of old versions is dropped immediately with the release
+of a new version. Please do not create issues before upgrading to the latest release available at the time. Regression
+reports are accepted and will be resolved with a new release as quickly as possible. Removed features will usually go
+through a deprecation cycle of a few minor releases.
+
+Resources:
+
+* **Source**: https://github.com/axnsan12/drf-yasg/
+* **Documentation**: https://drf-yasg.readthedocs.io/
+* **Changelog**: https://drf-yasg.readthedocs.io/en/stable/changelog.html
+* **Live demo**: https://drf-yasg-demo.herokuapp.com/
+
+|heroku-button|
 
 ********
 Features
 ********
 
--  full support for nested Serializers and Schemas
--  response schemas and descriptions
--  model definitions compatible with codegen tools
--  customization hooks at all points in the spec generation process
--  JSON and YAML format for spec
--  bundles latest version of
-   `swagger-ui <https://github.com/swagger-api/swagger-ui>`__ and
-   `redoc <https://github.com/Rebilly/ReDoc>`__ for viewing the generated documentation
--  schema view is cacheable out of the box
--  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>`__
+- full support for nested Serializers and Schemas
+- response schemas and descriptions
+- model definitions compatible with codegen tools
+- customization hooks at all points in the spec generation process
+- JSON and YAML format for spec
+- bundles latest version of
+  `swagger-ui <https://github.com/swagger-api/swagger-ui>`_ and
+  `redoc <https://github.com/Rebilly/ReDoc>`_ for viewing the generated documentation
+- schema view is cacheable out of the box
+- generated Swagger schema can be automatically validated by
+  `swagger-spec-validator <https://github.com/Yelp/swagger_spec_validator>`_
+- 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%
@@ -76,14 +91,14 @@ The preferred instalation method is directly from pypi:
 
 .. code:: console
 
-   pip install drf-yasg
+   pip install -U drf-yasg
 
 Additionally, if you want to use the built-in validation mechanisms (see `4. Validation`_), you need to install
 some extra requirements:
 
 .. code:: console
 
-   pip install drf-yasg[validation]
+   pip install -U drf-yasg[validation]
 
 .. _readme-quickstart:
 
@@ -94,44 +109,44 @@ In ``settings.py``:
 
 .. code:: python
 
-    INSTALLED_APPS = [
-        ...
-        'drf_yasg',
-        ...
-    ]
+   INSTALLED_APPS = [
+      ...
+      'drf_yasg',
+      ...
+   ]
 
 In ``urls.py``:
 
 .. code:: python
 
-    ...
-    from drf_yasg.views import get_schema_view
-    from drf_yasg import openapi
+   ...
+   from rest_framework import permissions
+   from drf_yasg.views import get_schema_view
+   from drf_yasg import openapi
 
-    ...
+   ...
 
-    schema_view = get_schema_view(
-        openapi.Info(
-            title="Snippets API",
-            default_version='v1',
-            description="Test description",
-            terms_of_service="https://www.google.com/policies/terms/",
-            contact=openapi.Contact(email="contact@snippets.local"),
-            license=openapi.License(name="BSD License"),
-        ),
-        validators=['ssv', 'flex'],
-        public=True,
-        permission_classes=(permissions.AllowAny,),
-    )
+   schema_view = get_schema_view(
+      openapi.Info(
+         title="Snippets API",
+         default_version='v1',
+         description="Test description",
+         terms_of_service="https://www.google.com/policies/terms/",
+         contact=openapi.Contact(email="contact@snippets.local"),
+         license=openapi.License(name="BSD License"),
+      ),
+      public=True,
+      permission_classes=(permissions.AllowAny,),
+   )
 
-    urlpatterns = [
-        url(r'^swagger(?P<format>.json|.yaml)$', schema_view.without_ui(cache_timeout=None), name='schema-json'),
-        url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=None), name='schema-swagger-ui'),
-        url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=None), name='schema-redoc'),
-        ...
-    ]
+   urlpatterns = [
+      url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
+      url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
+      url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
+      ...
+   ]
 
-This exposes 4 cached, validated and publicly available endpoints:
+This exposes 4 endpoints:
 
 * A JSON view of your API specification at ``/swagger.json``
 * A YAML view of your API specification at ``/swagger.yaml``
@@ -141,18 +156,21 @@ This exposes 4 cached, validated and publicly available endpoints:
 2. Configuration
 ================
 
+---------------------------------
 a. ``get_schema_view`` parameters
 ---------------------------------
 
-- ``info`` - Required. Swagger API Info object
+- ``info`` - Swagger API Info object; if omitted, defaults to ``DEFAULT_INFO``
 - ``url`` - 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`` - if False, includes only endpoints the current user has access to
-- ``validators`` - a list of validator names to apply on the generated schema; allowed values are ``flex``, ``ssv``
+- ``validators`` - a list of validator names to apply on the generated schema; only ``ssv`` is currently supported
+- ``generator_class`` - schema generator class to use; should be a subclass of ``OpenAPISchemaGenerator``
 - ``authentication_classes`` - authentication classes for the schema view itself
 - ``permission_classes`` - permission classes for the schema view itself
 
+-------------------------------
 b. ``SchemaView`` options
 -------------------------------
 
@@ -164,55 +182,17 @@ b. ``SchemaView`` options
    but with optional caching
 -  you can, of course, call :python:`as_view` as usual
 
-All of the first 3 methods take two optional arguments,
-``cache_timeout`` and ``cache_kwargs``; if present, these are passed on
-to Django’s :python:`cached_page` decorator in order to enable caching on the
-resulting view. See `3. Caching`_.
+All of the first 3 methods take two optional arguments, ``cache_timeout`` and ``cache_kwargs``; if present,
+these are passed on to Django’s :python:`cached_page` decorator in order to enable caching on the resulting view.
+See `3. Caching`_.
 
+----------------------------------------------
 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 = {
-        '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
 ==========
@@ -223,16 +203,16 @@ caching the schema view in-memory, with some sane defaults:
 * caching is enabled by the `cache_page <https://docs.djangoproject.com/en/1.11/topics/cache/#the-per-view-cache>`__
   decorator, using the default Django cache backend, can be changed using the ``cache_kwargs`` argument
 * HTTP caching of the response is blocked to avoid confusing situations caused by being shown stale schemas
-* if `public` is set to ``False`` on the SchemaView, the cached schema varies on the ``Cookie`` and ``Authorization``
-  HTTP headers to enable filtering of visible endpoints according to the authentication credentials of each user; note
-  that this means that every user accessing the schema will have a separate schema cached in memory.
+* the cached schema varies on the ``Cookie`` and ``Authorization`` HTTP headers to enable filtering of visible endpoints
+  according to the authentication credentials of each user; note that this means that every user accessing the schema
+  will have a separate schema cached in memory.
 
 4. Validation
 =============
 
-Given the numerous methods to manually customzie the generated schema, it makes sense to validate the result to ensure
+Given the numerous methods to manually customize the generated schema, it makes sense to validate the result to ensure
 it still conforms to OpenAPI 2.0. To this end, validation is provided at the generation point using python swagger
-libraries, and can be activated by passing :python:`validators=['ssv', 'flex']` to ``get_schema_view``; if the generated
+libraries, and can be activated by passing :python:`validators=['ssv']` to ``get_schema_view``; if the generated
 schema is not valid, a :python:`SwaggerValidationError` is raised by the handling codec.
 
 **Warning:** This internal validation can slow down your server.
@@ -241,6 +221,7 @@ Caching can mitigate the speed impact of validation.
 The provided validation will catch syntactic errors, but more subtle violations of the spec might slip by them. To
 ensure compatibility with code generation tools, it is recommended to also employ one or more of the following methods:
 
+-------------------------------
 ``swagger-ui`` validation badge
 -------------------------------
 
@@ -254,7 +235,7 @@ Offline
 ^^^^^^^
 
 If your schema is not accessible from the internet, you can run a local copy of
-`swagger-validator <https://hub.docker.com/r/swaggerapi/swagger-validator/>`_ and set the `VALIDATOR_URL` accordingly:
+`swagger-validator <https://hub.docker.com/r/swaggerapi/swagger-validator/>`_ and set the ``VALIDATOR_URL`` accordingly:
 
 .. code:: python
 
@@ -271,6 +252,7 @@ If your schema is not accessible from the internet, you can run a local copy of
     $ curl http://localhost:8189/debug?url=http://test.local:8002/swagger/?format=openapi
     {}
 
+---------------------
 Using ``swagger-cli``
 ---------------------
 
@@ -283,6 +265,7 @@ https://www.npmjs.com/package/swagger-cli
     $ swagger-cli validate http://test.local:8002/swagger.yaml
     http://test.local:8002/swagger.yaml is valid
 
+--------------------------------------------------------------
 Manually on `editor.swagger.io <https://editor.swagger.io/>`__
 --------------------------------------------------------------
 
@@ -303,52 +286,42 @@ You can use the specification outputted by this library together with
 
 See the github page linked above for more details.
 
-**********
-Background
-**********
+.. _readme-testproj:
 
-``OpenAPI 2.0``/``Swagger`` is a format designed to encode information about a Web API into an easily parsable schema
-that can then be used for rendering documentation, generating code, etc.
+6. Example project
+==================
 
-More details are available on `swagger.io <https://swagger.io/>`__ and on the `OpenAPI 2.0 specification
-page <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>`__.
+For additional usage examples, you can take a look at the test project in the ``testproj`` directory:
 
-From here on, the terms “OpenAPI” and “Swagger” are used interchangeably.
+.. code:: console
 
-Swagger in Django Rest Framework
-================================
+   $ git clone https://github.com/axnsan12/drf-yasg.git
+   $ cd drf-yasg
+   $ virtualenv venv
+   $ source venv/bin/activate
+   (venv) $ cd testproj
+   (venv) $ python -m pip install -U pip setuptools
+   (venv) $ pip install -U -r requirements.txt
+   (venv) $ python manage.py migrate
+   (venv) $ python manage.py runserver
+   (venv) $ firefox localhost:8000/swagger/
 
-Since Django Rest 3.7, there is now `built in support <http://www.django-rest-framework.org/api-guide/schemas/>`__ for
-automatic OpenAPI 2.0 schema generation. However, this generation is based on the `coreapi <http://www.coreapi.org/>`__
-standard, which for the moment is vastly inferior to OpenAPI in both features and tooling support. In particular,
-the OpenAPI codec/compatibility layer provided has a few major problems:
+************************
+Third-party integrations
+************************
 
-* there is no support for documenting response schemas and status codes
-* nested schemas do not work properly
-* does not handle more complex fields such as ``FileField``, ``ChoiceField``, …
+djangorestframework-camel-case
+===============================
 
-In short this makes the generated schema unusable for code generation, and mediocre at best for documentation.
+Integration with `djangorestframework-camel-case <https://github.com/vbabiy/djangorestframework-camel-case>`_ is
+provided out of the box - if you have ``djangorestframework-camel-case`` installed and your ``APIView`` uses
+``CamelCaseJSONParser`` or ``CamelCaseJSONRenderer``, all property names will be converted to *camelCase* by default.
 
-Other libraries
-===============
+djangorestframework-recursive
+===============================
 
-There are currently two decent Swagger schema generators that I could
-find for django-rest-framework:
-
-* `django-rest-swagger <https://github.com/marcgibbons/django-rest-swagger>`__
-* `drf-openapi <https://github.com/limdauto/drf_openapi>`__
-
-Out of the two, ``django-rest-swagger`` is just a wrapper around DRF 3.7 schema generation with an added UI, and
-thus presents the same problems. ``drf-openapi`` is a bit more involved and implements some custom handling for response
-schemas, but ultimately still falls short in code generation because the responses are plain of lacking support for
-named schemas.
-
-Both projects are also currently unmantained.
-
-Documentation, advanced usage
-=============================
-
-https://drf-yasg.readthedocs.io/en/latest/
+Integration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_ is
+provided out of the box - if you have ``djangorestframework-recursive`` installed.
 
 .. |travis| image:: https://img.shields.io/travis/axnsan12/drf-yasg/master.svg
    :target: https://travis-ci.org/axnsan12/drf-yasg
@@ -359,12 +332,20 @@ https://drf-yasg.readthedocs.io/en/latest/
    :alt: Codecov
 
 .. |pypi-version| image:: https://img.shields.io/pypi/v/drf-yasg.svg
-   :target: https://pypi.python.org/pypi/drf-yasg/
+   :target: https://pypi.org/project/drf-yasg/
    :alt: PyPI
 
 .. |rtd-badge| image:: https://img.shields.io/readthedocs/drf-yasg.svg
    :target: https://drf-yasg.readthedocs.io/
    :alt: ReadTheDocs
 
+.. |bmac-button| image:: https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png
+   :target: https://www.buymeacoffee.com/cvijdea
+   :alt: Buy Me A Coffee
+
+.. |heroku-button| image:: https://www.herokucdn.com/deploy/button.svg
+   :target: https://heroku.com/deploy?template=https://github.com/axnsan12/drf-yasg
+   :alt: Heroku deploy button
+
 .. |nbsp| unicode:: 0xA0
    :trim:

app.json

@@ -0,0 +1,17 @@
+{
+  "name": "drf-yasg Demo app",
+  "description": "A demonstrative app using https://github.com/axnsan12/drf-yasg",
+  "repository": "https://github.com/axnsan12/drf-yasg",
+  "logo": "https://swaggerhub.com/wp-content/uploads/2017/10/Swagger-Icon.svg",
+  "keywords": [
+    "django",
+    "django-rest-framework",
+    "swagger",
+    "openapi"
+  ],
+  "env": {
+    "DJANGO_SETTINGS_MODULE": "testproj.settings.heroku",
+    "DJANGO_SECRET_KEY": "m76=^#=z7xv5^(o%4dv9w7+1_c)y2m6)1ogjx%s@9$1^nupry="
+  },
+  "success_url": "/"
+}

docs/_static/css/style.css

@@ -0,0 +1,18 @@
+.versionadded, .versionchanged, .deprecated {
+    font-family: "Roboto", Corbel, Avenir, "Lucida Grande", "Lucida Sans", sans-serif;
+    padding: 10px 13px;
+    border: 1px solid rgb(137, 191, 4);
+    border-radius: 4px;
+    margin-bottom: 10px;
+}
+
+.versionmodified {
+    font-weight: bold;
+    display: block;
+}
+
+.versionadded p, .versionchanged p, .deprecated p,
+/*override fucking !important by being more specific */
+.rst-content dl .versionadded p, .rst-content dl .versionchanged p {
+    margin: 0 !important;
+}

docs/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <meta name="google-site-verification" content="saewLzcrUS1lAAgNVIikKWc3DUbFcE-TWtpyw3AW8CA" />
+{% endblock %}

docs/changelog.rst

@@ -3,10 +3,569 @@ Changelog
 #########
 
 
+**********
+**1.17.1**
+**********
+
+*Release date: Feb 17, 2020*
+
+- **FIXED:** fixed compatibility issue with CurrentUserDefault in Django Rest Framework 3.11
+- **FIXED:** respect `USERNAME_FIELD` in `generate_swagger` command (:pr:`486`)
+
+**Support was dropped for Python 3.5, Django 2.0, Django 2.1, DRF 3.7**
+
+**********
+**1.17.0**
+**********
+
+*Release date: Oct 03, 2019*
+
+- **ADDED:** added `JSONFieldInspector` for `JSONField` support (:pr:`417`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.23.11
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.14 (:issue:`398`)
+- **FIXED:** fixed a type hint support issue (:pr:`428`, :issue:`450`)
+- **FIXED:** fixed packaging issue caused by a missing requirement (:issue:`412`)
+
+**********
+**1.16.1**
+**********
+
+*Release date: Jul 16, 2019*
+
+- **IMPROVED:** better enum type detection for nested `ChoiceField`\ s (:pr:`400`)
+- **FIXED:** fixed DRF 3.10 compatibility (:pr:`408`, :issue:`410`, :issue:`411`)
+
+**********
+**1.16.0**
+**********
+
+*Release date: Jun 13, 2019*
+
+- **ADDED:** added `reference_resolver_class` attribute hook to `SwaggerAutoSchema` (:pr:`350`)
+- **ADDED:** added `operation_keys` attribute to `SwaggerAutoSchema`, along with `__init__` parameter (:pr:`355`)
+- **FIXED:** fixed potential crash on `issubclass` check without `isclass` check
+
+**********
+**1.15.1**
+**********
+
+*Release date: Jun 13, 2019*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.22.3
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.8-1
+- **FIXED:** fixed an issue with inspection of typing hints on Python 2.7 (:issue:`363`)
+- **FIXED:** fixed an issue with inspection of typing hints on Python 3.7 (:issue:`371`)
+
+**Python 3.4 support has been dropped!**
+
+**********
+**1.15.0**
+**********
+
+*Release date: Apr 01, 2019*
+
+- **ADDED:** added ``is_list_view`` and ``has_list_response`` extension points to ``SwaggerAutoSchema`` (:issue:`331`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.22.0
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.4
+- **FIXED:** ``ListModelMixin`` will now always be treated as a list view (:issue:`306`)
+- **FIXED:** non-primtive values in field ``choices`` will now be handled properly (:issue:`340`)
+
+**********
+**1.14.0**
+**********
+
+*Release date: Mar 04, 2019*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.21.0
+- **FIXED:** implicit ``ref_name`` collisions will now throw an exception
+- **FIXED:** ``RecursiveField`` will now also work as a child of ``ListSerializer`` (:pr:`321`)
+- **FIXED:** fixed ``minLength`` and ``maxLength`` for ``ListSerializer`` and ``ListField``
+- **FIXED:** the ``items`` property of ``Schema``, ``Parameter`` and ``Items`` objects was renamed to ``items_``; this
+  is a *mildly breaking change* and was needed to fix the collision with the ``items`` method of ``dict`` (:pr:`308`)
+- **REMOVED:** the ``get_summary`` and ``get_description`` methods have been removed (previously deprecated in 1.12.0)
+
+**********
+**1.13.0**
+**********
+
+*Release date: Jan 29, 2019*
+
+- **IMPROVED:** type hint inspection is now supported for collections and ``Optional`` (:pr:`272`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.20.5
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.2
+- **DEPRECATED:** quietly dropped support for the ``flex`` validator; it will still work if the library is installed,
+  but the setup.py requirement was removed and the validator will be silently skipped if not installed (:issue:`285`)
+
+**********
+**1.12.1**
+**********
+
+*Release date: Dec 28, 2018*
+
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.0
+- **FIXED:** management command will now correctly fall back to ``DEFAULT_VERSION`` for mock request
+- **FIXED:** fixed bad "raised exception during schema generation" warnings caused by missing ``self`` parameter
+
+**********
+**1.12.0**
+**********
+
+*Release date: Dec 23, 2018*
+
+- **ADDED:** ``get_security_definitions`` and ``get_security_requirements`` hooks to ``OpenAPISchemaGenerator``
+- **ADDED:** added ``get_summary_and_description`` and ``split_summary_from_description`` extension points to
+  ``SwaggerAutoSchema`` to allow for better customisation
+- **IMPROVED:** updated ``swagger-ui`` to version 3.20.4
+- **IMPROVED:** paginator ``next`` and ``previous`` fields are now marked as ``x-nullable`` (:issue:`263`)
+- **IMPROVED:** added the ``tags`` argument to ``swagger_auto_schema`` (:pr:`259`)
+- **IMPROVED:** type of ``enum`` will now be automatically detected from ``ChoiceField`` if all ``choices`` values
+  are objects of the same Python class (:pr:`264`)
+- **IMPROVED:** ``SwaggerValidationError`` details will now be logged and shown in the exception message
+- **FIXED:** user implementations of ``get_queryset``, ``get_parsers`` and ``get_renderers`` will no longer be bypassed
+- **FIXED:** fixed handling of lazy objects in user-supplied values
+- **FIXED:** ``read_only`` serializer fields will be correctly ignored when generating form parameters (:issue:`261`)
+- **FIXED:** fixed incorrect return type from ``UIRenderer`` (:pr:`268`)
+- **FIXED:** fixed incosistent ordering of global ``securityDefinitions`` and ``security`` objects
+- **DEPRECATED:** the ``get_summary`` and ``get_description`` extension points have been deprecated in favor of the
+  new ``get_summary_and_description``, and will be removed in a future release
+
+**IMPORTANT PACKAGING NOTE**
+
+Starting with this version, the ``setup_requires`` argument was dropped from ``setup.py`` in favor of
+``build-system.requires`` in ``pyproject.toml`` . This means that for correctly building or installing from sdist,
+you will need to use a PEP517/PEP518 compliant tool (tox>=3.3.0, setuptools>=40, pip>=10.0, pep517.build) or manually
+install the build requirements yourself (just ``setuptools`` and ``setuptools-scm``, for now).
+
+Additionally, for correct package version detection, a full git checkout is required when building (this was always the
+case). Building without ``.git`` or without ``setuptools-scm`` will result in a distribution with a version like
+``drf-yasg-1!0.0.0.dev0+noscm.00000167d19bd859``.
+
+**********
+**1.11.1**
+**********
+
+*Release date: Nov 29, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.20.1
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.41
+- **FIXED:** ``minLength`` and ``maxLength`` will now also work for ``ListSerializer`` in addition to ``ListField``
+- **FIXED:** ``MultipleChoiceField`` will now use the ``multi`` ``collectionFormat`` where appropriate (:issue:`257`)
+- **FIXED:** the ``format``, ``pattern``, ``enum``, ``min_length`` and ``max_length`` attributes of
+  ``coreschema.Schema`` will now be persited into the converted ``openapi.Parameter`` (:issue:`212`, :pr:`233`)
+
+**********
+**1.11.0**
+**********
+
+*Release date: Oct 14, 2018*
+
+- **ADDED:** ``PERSIST_AUTH``, ``REFETCH_SCHEMA_WITH_AUTH``, ``REFETCH_SCHEMA_ON_LOGOUT``
+  settings and related javascript implementation for persisting authentication data to swagger-ui localStorage
+- **IMPROVED:** UI-enabled views will now no longer generate the full specification document twice; the HTML part
+  of the view will only generate a barebones ``Swagger`` object with no ``paths`` and ``definitions``
+- **IMPROVED:** added the ``FETCH_SCHEMA_WITH_QUERY`` setting to enable fetching of the schema document using
+  query parameters passed to the UI view (:issue:`208`)
+- **IMPROVED:** added support for the very common ``x-nullable`` extension (:issue:`217`)
+- **IMPROVED:** extensibility of some classes was improved by adding more extension points, together with more blocks
+  for ``swagger-ui.html``/``redoc.html`` and some JavaScript hooks in ``swagger-ui-init.js``
+- **FIXED:** removed usage of ``inspect.signature`` on python 2.7 (:issue:`222`)
+
+**********
+**1.10.2**
+**********
+
+*Release date: Sep 13, 2018*
+
+- **ADDED:** added the ``DISPLAY_OPERATION_ID`` ``swagger-ui`` setting
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.38
+- **IMPROVED:** Operation summary will now be parsed from multi-line view method docstrings (:issue:`205`)
+- **IMPROVED:** ``pattern`` will now work on any field with a ``RegexValidator``
+  (would previously not appear on fields with special formats such as ``EmailField``)
+- **FIXED:** fixed an issue with ``RelatedFieldInspector`` handling of nested serializers
+- **FIXED:** fixed handling of ``reverse_lazy`` in URL settings (:issue:`209`)
+
+**********
+**1.10.1**
+**********
+
+*Release date: Sep 10, 2018*
+
+- **ADDED:** added the ``SPEC_URL`` setting for controlling the download link in ``swagger-ui`` and ``ReDoc``
+- **ADDED:** updated ``ReDoc`` settings (added ``NATIVE_SCROLLBARS`` and ``REQUIRED_PROPS_FIRST``)
+- **ADDED:** added ``extra_styles`` and ``extra_scripts`` blocks to ui templates (:issue:`178`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.18.2
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.37
+- **FIXED:** stopped generating invalid OpenAPI by improper placement of ``readOnly`` Schemas
+- **FIXED:** fixed broken CSS when ``USE_SESSION_AUTH=False``
+- **FIXED:** fixed implementation of ``operation_summary`` and ``deprecated`` (:pr:`194`, :pr:`198`)
+- **FIXED:** fixed a bug related to nested ``typing`` hints (:pr:`195`)
+- **FIXED:** removed dependency on ``future`` (:issue:`196`)
+- **FIXED:** fixed exceptions logged for fields with ``default=None`` (:issue:`203`)
+- **FIXED:** fixed ``request_body=no_body`` handling and related tests (:issue:`188`, :issue:`199`)
+
+
+**********
+**1.10.0**
+**********
+
+*Release date: Aug 08, 2018*
+
+- **ADDED:** added ``EXCLUDED_MEDIA_TYPES`` setting for controlling ``produces`` MIME type filtering (:issue:`158`)
+- **ADDED:** added support for ``SerializerMethodField``, via the ``swagger_serializer_method`` decorator for the
+  method field, and support for Python 3.5 style type hinting of the method field return type
+  (:issue:`137`, :pr:`175`, :pr:`179`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.SerializerMethodFieldInspector``
+  to your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.18.0
+- **IMPROVED:** added support for Python 3.7 and Django 2.1 (:pr:`176`)
+- **IMPROVED:** ``swagger_schema_fields`` will now also work on serializer ``Field``\ s (:issue:`167`)
+- **IMPROVED:** ``ref_name`` collisions will now log a warning message (:issue:`156`)
+- **IMPROVED:** added ``operation_summary`` and ``deprecated`` arguments to ``swagger_auto_schema``
+  (:issue:`149`, :issue:`173`)
+- **FIXED:** made ``swagger_auto_schema`` work with DRF 3.9 ``@action`` mappings (:issue:`177`)
+
+*********
+**1.9.2**
+*********
+
+*Release date: Aug 03, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.17.6
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.32
+- **IMPROVED:** added ``--api-version`` argument to the ``generate_swagger`` management command (:pr:`170`)
+- **FIXED:** corrected various documentation typos (:pr:`160`, :pr:`162`, :issue:`171`, :pr:`172`)
+- **FIXED:** made ``generate_swagger`` work for projects without authentication (:pr:`161`)
+- **FIXED:** fixed ``SafeText`` interaction with YAML codec (:issue:`159`)
+
+*********
+**1.9.1**
+*********
+
+*Release date: Jun 30, 2018*
+
+- **IMPROVED:** added a ``swagger_fake_view`` marker to more easily detect mock views in view methods;
+  ``getattr(self, 'swagger_fake_view', False)`` inside a view method like ``get_serializer_class`` will tell you if the
+  view instance is being used for swagger schema introspection (:issue:`154`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.17.1
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.25
+- **FIXED:** fixed wrong handling of duplicate urls in urlconf (:pr:`155`)
+- **FIXED:** fixed crash when passing ``None`` as a response override (:issue:`148`)
+
+*********
+**1.9.0**
+*********
+
+*Release date: Jun 16, 2018*
+
+- **ADDED:** added ``DEFAULT_GENERATOR_CLASS`` setting and ``--generator-class`` argument to the ``generate_swagger``
+  management command (:issue:`140`)
+- **FIXED:** fixed wrongly required ``'count'`` response field on ``CursorPagination`` (:issue:`141`)
+- **FIXED:** fixed some cases where ``swagger_schema_fields`` would not be handlded (:pr:`142`)
+- **FIXED:** fixed crash when encountering ``coreapi.Fields``\ s without a ``schema`` (:issue:`143`)
+
+*********
+**1.8.0**
+*********
+
+*Release date: Jun 01, 2018*
+
+- **ADDED:** added a :ref:`swagger_schema_fields <swagger_schema_fields>` field on serializer ``Meta`` classes for
+  customizing schema generation (:issue:`132`, :pr:`134`)
+- **FIXED:** error responses from schema views are now rendered with ``JSONRenderer`` instead of throwing
+  confusing errors (:pr:`130`, :issue:`58`)
+- **FIXED:** ``readOnly`` schema fields will now no longer be marked as ``required`` (:pr:`133`)
+
+*********
+**1.7.4**
+*********
+
+*Release date: May 14, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.14.2
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.20
+- **FIXED:** ignore ``None`` return from ``get_operation`` to avoid empty ``Path`` objects in output
+- **FIXED:** request body is now allowed on ``DELETE`` endpoints (:issue:`118`)
+
+*********
+**1.7.3**
+*********
+
+*Release date: May 12, 2018*
+
+- **FIXED:** views whose ``__init__`` methods throw exceptions will now be ignored during endpoint enumeration
+
+*********
+**1.7.2**
+*********
+
+*Release date: May 12, 2018*
+
+- **FIXED:** fixed generation of default ``SECURITY_REQUIREMENTS`` to match documented behaviour
+- **FIXED:** ordering of ``SECURITY_REQUIREMENTS`` and ``SECURITY_DEFINITIONS`` is now stable
+
+*********
+**1.7.1**
+*********
+
+*Release date: May 05, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.14.1
+- **IMPROVED:** set ``swagger-ui`` ``showCommonExtensions`` to ``True`` by default and add
+  ``SHOW_COMMON_EXTENSIONS`` setting key
+- **IMPROVED:** set ``min_length=1`` when ``allow_blank=False`` (:pr:`112`, thanks to :ghuser:`elnappo`)
+- **FIXED:** made documentation ordering of ``SwaggerDict`` extra attributes stable
+
+*********
+**1.7.0**
+*********
+
+*Release date: Apr 27, 2018*
+
+- **ADDED:** added integration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_
+  (:issue:`109`, :pr:`110`, thanks to :ghuser:`rsichny`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.RecursiveFieldInspector`` to
+  your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **FIXED:** ``SchemaRef`` now supports cyclical references via the ``ignore_unresolved`` argument
+
+*********
+**1.6.2**
+*********
+
+*Release date: Apr 25, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.13.6
+- **IMPROVED:** switched ``ReDoc`` to version 2.0.0-alpha.17 (was 1.21.2); fixes :issue:`107`
+- **FIXED:** made documentation ordering of parameters stable for urls with multiple parameters (:issue:`105`, :pr:`106`)
+- **FIXED:** fixed crash when using a model ``ChoiceField`` of unknown child type
+
+*********
+**1.6.1**
+*********
+
+*Release date: Apr 01, 2018*
+
+- **ADDED:** added ``SUPPORTED_SUBMIT_METHODS`` ``swagger-ui`` setting
+
+*********
+**1.6.0**
+*********
+
+*Release date: Mar 24, 2018*
+
+- **IMPROVED:** ``OAUTH2_REDIRECT_URL`` will now default to the built in ``oauth2-redirect.html`` file
+
+*********
+**1.5.1**
+*********
+
+*Release date: Mar 18, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.13.0
+- **FIXED:** fixed a crash caused by ``serializers.OneToOneRel`` (:pr:`81`, thanks to :ghuser:`ko-pp`)
+
+*********
+**1.5.0**
+*********
+
+*Release date: Mar 12, 2018*
+
+- **IMPROVED:** ``serializers.HiddenField`` are now hidden (:issue:`78`, :pr:`79`, thanks to :ghuser:`therefromhere`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.HiddenFieldInspector`` to your
+  ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **IMPROVED:** type of model field is now detected for ``serializers.SlugRelatedField`` with ``read_only=True``
+  (:issue:`82`, :pr:`83`, thanks to :ghuser:`therefromhere`)
+
+*********
+**1.4.7**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **FIXED:** prevent crashes caused by attempting to delete object attributes which do not exist in the first place
+  (:issue:`76`)
+
+*********
+**1.4.6**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.12.0
+- **IMPROVED:** updated ``ReDoc`` to version 1.21.2
+
+*********
+**1.4.5**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **FIXED:** fixed an issue with modification of ``swagger_auto_schema`` arguments in-place during introspection, which
+  would sometimes cause an incomplete Swagger document to be generated after the first pass (:issue:`74`, :pr:`75`)
+
+*********
+**1.4.4**
+*********
+
+*Release date: Feb 26, 2018*
+
+- **IMPROVED:** ``type`` for ``ChoiceField`` generated by a ``ModelSerializer`` from a model field with ``choices=...``
+  will now be set according to the associated model field (:issue:`69`)
+- **FIXED:** ``lookup_field`` and ``lookup_value_regex`` on the same ``ViewSet``  will no longer trigger an exception
+  (:issue:`68`)
+
+*********
+**1.4.3**
+*********
+
+*Release date: Feb 22, 2018*
+
+- **FIXED:** added a missing assignment that would cause the ``default`` argument to ``openapi.Parameter.__init__`` to
+  be ignored
+
+*********
+**1.4.2**
+*********
+
+*Release date: Feb 22, 2018*
+
+- **FIXED:** fixed a bug that causes a ``ModelViewSet`` generated from models with nested ``ForeignKey`` to output
+  models named ``Nested`` into the ``definitions`` section (:issue:`59`, :pr:`65`)
+- **FIXED:** ``Response`` objects without a ``schema`` are now properly handled when passed through
+  ``swagger_auto_schema`` (:issue:`66`)
+
+*********
+**1.4.1**
+*********
+
+*Release date: Feb 21, 2018*
+
+- **FIXED:** the ``coerce_to_string`` is now respected when setting the type, default value and min/max values of
+  ``DecimalField`` in the OpenAPI schema (:issue:`62`)
+- **FIXED:** error responses from web UI views are now rendered with ``TemplateHTMLRenderer`` instead of throwing
+  confusing errors (:issue:`58`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.10.0
+- **IMPROVED:** updated ``ReDoc`` to version 1.21.0
+
+*********
+**1.4.0**
+*********
+
+*Release date: Feb 04, 2018*
+
+- **ADDED:** added settings for OAuth2 client configuration in ``swagger-ui`` (:issue:`53`)
+- **IMPROVED:** updated ``swagger-ui`` to version 3.9.3
+
+*********
+**1.3.1**
+*********
+
+*Release date: Jan 24, 2018*
+
+- **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**
+*********
+
+*Release date: Jan 23, 2018*
+
+- **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**
+*********
+
+*Release date: Jan 12, 2018*
+
+- **FIXED:** djangorestframework>=3.7.7 is now required because of breaking changes
+  (:issue:`44`, :pr:`45`, thanks to :ghuser:`h-hirokawa`)
+
+*********
+**1.2.1**
+*********
+
+*Release date: Jan 12, 2018*
+
+- Fixed deployment issues
+
+*********
+**1.2.0**
+*********
+
+*Release date: Jan 12, 2018 (missing from PyPI due to deployment issues)*
+
+- **ADDED:** ``basePath`` is now generated by taking into account the ``SCRIPT_NAME`` variable and the
+  longest common prefix of API urls (:issue:`37`, :pr:`42`)
+- **IMPROVED:** removed inline scripts and styles from bundled HTML templates to increase CSP compatibility
+- **IMPROVED:** improved validation errors and added more assertion sanity checks (:issue:`37`, :issue:`40`)
+- **IMPROVED:** improved handling of NamespaceVersioning by excluding endpoints of differing versions
+  (i.e. when accesing the schema view for v1, v2 endpoints will not be included in swagger)
+
+*********
+**1.1.3**
+*********
+
+*Release date: Jan 02, 2018*
+
+- **FIXED:** schema view cache will now always ``Vary`` on the ``Cookie`` and ``Authentication`` (the
+  ``Vary`` header was previously only added if ``public`` was set to ``True``) - this fixes issues related to Django
+  authentication in ``swagger-ui`` and ``CurrentUserDefault`` values in the schema
+
+*********
+**1.1.2**
+*********
+
+*Release date: Jan 01, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.8.1
+- **IMPROVED:** removed some unneeded static files
+
+*********
+**1.1.1**
+*********
+
+*Release date: Dec 27, 2017*
+
+- **ADDED:** :ref:`generate_swagger management command <management-command>`
+  (:issue:`29`, :pr:`31`, thanks to :ghuser:`beaugunderson`)
+- **FIXED:** fixed improper generation of ``\Z`` regex tokens - will now be repalced by ``$``
+
+*********
+**1.1.0**
+*********
+
+*Release date: Dec 27, 2017*
+
+- **ADDED:** added support for APIs versioned with ``URLPathVersioning`` or ``NamespaceVersioning``
+- **ADDED:** added ability to recursively customize schema generation
+  :ref:`using pluggable inspector classes <custom-spec-inspectors>`
+- **ADDED:** added ``operation_id`` parameter to :func:`@swagger_auto_schema <.swagger_auto_schema>`
+- **ADDED:** integration with `djangorestframework-camel-case
+  <https://github.com/vbabiy/djangorestframework-camel-case>`_ (:issue:`28`)
+- **IMPROVED:** strings, arrays and integers will now have min/max validation attributes inferred from the
+  field-level validators
+- **FIXED:** fixed a bug that caused ``title`` to never be generated for Schemas; ``title`` is now correctly
+  populated from the field's ``label`` property
+
 *********
 **1.0.6**
 *********
 
+*Release date: Dec 23, 2017*
+
 - **FIXED:** Swagger UI "Try it out!" should now work with Django login
 - **FIXED:** callable ``default`` values on serializer fields will now be properly called (:pr:`24`, :issue:`25`)
 - **IMPROVED:** updated ``swagger-ui`` to version 3.8.0
@@ -18,6 +577,8 @@ Changelog
 **1.0.5**
 *********
 
+*Release date: Dec 18, 2017*
+
 - **FIXED:** fixed a crash caused by having read-only Serializers nested by reference
 - **FIXED:** removed erroneous backslashes in paths when routes are generated using Django 2
   `path() <https://docs.djangoproject.com/en/2.0/ref/urls/#django.urls.path>`_
@@ -29,6 +590,8 @@ Changelog
 **1.0.4**
 *********
 
+*Release date: Dec 16, 2017*
+
 - **FIXED:** fixed improper generation of YAML references
 - **ADDED:** added ``query_serializer`` parameter to
   :func:`@swagger_auto_schema <.swagger_auto_schema>` (:issue:`16`, :pr:`17`)
@@ -37,6 +600,8 @@ Changelog
 **1.0.3**
 *********
 
+*Release date: Dec 15, 2017*
+
 - **FIXED:** fixed bug that caused schema views returned from cache to fail (:issue:`14`)
 - **FIXED:** disabled automatic generation of response schemas for form operations to avoid confusing errors caused by
   attempting to shove file parameters into Schema objects
@@ -45,4 +610,6 @@ Changelog
 **1.0.2**
 *********
 
+*Release date: Dec 13, 2017*
+
 - First published version

docs/conf.py

@@ -3,6 +3,7 @@
 #
 # drf-yasg documentation build configuration file, created by
 # sphinx-quickstart on Sun Dec 10 15:20:34 2017.
+import inspect
 import os
 import re
 import sys
@@ -38,7 +39,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'drf-yasg'
-copyright = '2017, Cristi V.'
+copyright = '2018, Cristi V.'
 author = 'Cristi V.'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -47,6 +48,11 @@ author = 'Cristi V.'
 
 # The full version, including alpha/beta/rc tags.
 release = get_distribution('drf_yasg').version
+if 'noscm' in release:
+    raise AssertionError('Invalid package version string: %s. \n'
+                         'The documentation must be built with drf_yasg installed from a distribution package, '
+                         'which must have been built with a proper version number (i.e. from a full source checkout).'
+                         % (release,))
 
 # The short X.Y.Z version.
 version = '.'.join(release.split('.')[:3])
@@ -68,9 +74,6 @@ pygments_style = 'sphinx'
 
 modindex_common_prefix = ['drf_yasg.']
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -157,18 +160,35 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
-autodoc_default_flags = ['private-members']
+autodoc_default_options = {
+    'private-members': None
+}
 autodoc_member_order = 'bysource'
 autoclass_content = 'both'
 autodoc_mock_imports = []
 
 nitpick_ignore = [
     ('py:class', 'object'),
+    ('py:class', 'bool'),
+    ('py:class', 'dict'),
+    ('py:class', 'list'),
+    ('py:class', 'str'),
+    ('py:class', 'int'),
+    ('py:class', 'bytes'),
+    ('py:class', 'tuple'),
+    ('py:class', 'function'),
+    ('py:class', 'type'),
+    ('py:class', 'OrderedDict'),
+    ('py:class', 'None'),
+    ('py:obj', 'None'),
+
     ('py:class', 'Exception'),
     ('py:class', 'collections.OrderedDict'),
 
     ('py:class', 'ruamel.yaml.dumper.SafeDumper'),
+    ('py:class', 'rest_framework.serializers.Serializer'),
     ('py:class', 'rest_framework.renderers.BaseRenderer'),
+    ('py:class', 'rest_framework.parsers.BaseParser'),
     ('py:class', 'rest_framework.schemas.generators.EndpointEnumerator'),
     ('py:class', 'rest_framework.views.APIView'),
 
@@ -176,26 +196,17 @@ nitpick_ignore = [
     ('py:class', 'OpenAPICodecJson'),
     ('py:class', 'OpenAPISchemaGenerator'),
 
-    ('py:obj', 'bool'),
-    ('py:obj', 'dict'),
-    ('py:obj', 'list'),
-    ('py:obj', 'str'),
-    ('py:obj', 'int'),
-    ('py:obj', 'bytes'),
-    ('py:obj', 'tuple'),
-    ('py:obj', 'callable'),
-    ('py:obj', 'type'),
-    ('py:obj', 'OrderedDict'),
-
-    ('py:obj', 'coreapi.Field'),
-    ('py:obj', 'BaseFilterBackend'),
-    ('py:obj', 'BasePagination'),
-    ('py:obj', 'rest_framework.request.Request'),
-    ('py:obj', 'rest_framework.serializers.Field'),
-    ('py:obj', 'serializers.Field'),
-    ('py:obj', 'serializers.BaseSerializer'),
-    ('py:obj', 'Serializer'),
-    ('py:obj', 'APIView'),
+    ('py:class', 'coreapi.Field'),
+    ('py:class', 'BaseFilterBackend'),
+    ('py:class', 'BasePagination'),
+    ('py:class', 'Request'),
+    ('py:class', 'rest_framework.request.Request'),
+    ('py:class', 'rest_framework.serializers.Field'),
+    ('py:class', 'serializers.Field'),
+    ('py:class', 'serializers.BaseSerializer'),
+    ('py:class', 'Serializer'),
+    ('py:class', 'BaseSerializer'),
+    ('py:class', 'APIView'),
 ]
 
 # even though the package should be already installed, the sphinx build on RTD
@@ -204,7 +215,7 @@ sys.path.insert(0, os.path.abspath('../src'))
 
 # activate the Django testproj to be able to succesfully import drf_yasg
 sys.path.insert(0, os.path.abspath('../testproj'))
-os.putenv('DJANGO_SETTINGS_MODULE', 'testproj.settings')
+os.putenv('DJANGO_SETTINGS_MODULE', 'testproj.settings.local')
 
 from django.conf import settings  # noqa: E402
 
@@ -215,6 +226,40 @@ import drf_yasg.views  # noqa: E402
 
 drf_yasg.views.SchemaView = drf_yasg.views.get_schema_view(None)
 
+# monkey patch to stop sphinx from trying to find classes by their real location instead of the
+# top-level __init__ alias; this allows us to document only `drf_yasg.inspectors` and avoid broken references or
+# double documenting
+
+import drf_yasg.inspectors  # noqa: E402
+
+
+def redirect_cls(cls):
+    if cls.__module__.startswith('drf_yasg.inspectors'):
+        return getattr(drf_yasg.inspectors, cls.__name__)
+    return cls
+
+
+for cls_name in drf_yasg.inspectors.__all__:
+    # first pass - replace all classes' module with the top level module
+    real_cls = getattr(drf_yasg.inspectors, cls_name)
+    if not inspect.isclass(real_cls):
+        continue
+
+    patched_dict = dict(real_cls.__dict__)
+    patched_dict.update({'__module__': 'drf_yasg.inspectors'})
+    patched_cls = type(cls_name, real_cls.__bases__, patched_dict)
+    setattr(drf_yasg.inspectors, cls_name, patched_cls)
+
+for cls_name in drf_yasg.inspectors.__all__:
+    # second pass - replace the inheritance bases for all classes to point to the new clean classes
+    real_cls = getattr(drf_yasg.inspectors, cls_name)
+    if not inspect.isclass(real_cls):
+        continue
+
+    patched_bases = tuple(redirect_cls(base) for base in real_cls.__bases__)
+    patched_cls = type(cls_name, patched_bases, dict(real_cls.__dict__))
+    setattr(drf_yasg.inspectors, cls_name, patched_cls)
+
 # custom interpreted role for linking to GitHub issues and pull requests
 # use as :issue:`14` or :pr:`17`
 gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/{}"
@@ -238,7 +283,7 @@ def role_github_user(name, rawtext, text, lineno, inliner, options=None, content
     options = options or {}
     content = content or []
 
-    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text):
+    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text, re.IGNORECASE):
         return sphinx_err(inliner, lineno, rawtext, '"%s" is not a valid GitHub username.' % text)
 
     ref = gh_user_uri.format(text)
@@ -273,3 +318,7 @@ def role_github_pull_request_or_issue(name, rawtext, text, lineno, inliner, opti
 roles.register_local_role('pr', role_github_pull_request_or_issue)
 roles.register_local_role('issue', role_github_pull_request_or_issue)
 roles.register_local_role('ghuser', role_github_user)
+
+
+def setup(app):
+    app.add_stylesheet('css/style.css')

docs/custom_spec.rst

@@ -9,125 +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`
-
-* :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>`_
+      # all methods of the UserList class will be excluded
+      ...
 
+   # 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:
 
@@ -138,7 +43,9 @@ The ``@swagger_auto_schema`` decorator
 You can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decorator on view functions to override
 some properties of the generated :class:`.Operation`. For example, in a ``ViewSet``,
 
-.. code:: python
+.. code-block:: python
+
+   from drf_yasg.utils import swagger_auto_schema
 
    @swagger_auto_schema(operation_description="partial_update description override", responses={404: 'slug not found'})
    def partial_update(self, request, *args, **kwargs):
@@ -153,7 +60,7 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
 * for function based ``@api_view``\ s, because the same view can handle multiple methods, and thus represent multiple
   operations, you have to add the decorator multiple times if you want to override different operations:
 
-   .. code:: python
+   .. code-block:: python
 
       test_param = openapi.Parameter('test', openapi.IN_QUERY, description="test manual param", type=openapi.TYPE_BOOLEAN)
       user_response = openapi.Response('response description', UserSerializer)
@@ -169,7 +76,7 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
 * for class based ``APIView``, ``GenericAPIView`` and non-``ViewSet`` derivatives, you have to decorate the respective
   method of each operation:
 
-   .. code:: python
+   .. code-block:: python
 
       class UserList(APIView):
          @swagger_auto_schema(responses={200: UserSerializer(many=True)})
@@ -182,22 +89,22 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
 
 * for ``ViewSet``, ``GenericViewSet``, ``ModelViewSet``, because each viewset corresponds to multiple **paths**, you have
   to decorate the *action methods*, i.e. ``list``, ``create``, ``retrieve``, etc. |br|
-  Additionally, ``@list_route``\ s or ``@detail_route``\ s defined on the viewset, like function based api views, can
-  respond to multiple HTTP methods and thus have multiple operations that must be decorated separately:
+  Additionally, ``@action``\ s defined on the viewset, like function based api views, can respond to multiple HTTP
+  methods and thus have multiple operations that must be decorated separately:
 
 
-   .. code:: python
+   .. code-block:: python
 
       class ArticleViewSet(viewsets.ModelViewSet):
-         # method or 'methods' can be skipped because the list_route only handles a single method (GET)
+         # method or 'methods' can be skipped because the action only handles a single method (GET)
          @swagger_auto_schema(operation_description='GET /articles/today/')
-         @list_route(methods=['get'])
+         @action(detail=False, methods=['get'])
          def today(self, request):
             ...
 
          @swagger_auto_schema(method='get', operation_description="GET /articles/{id}/image/")
          @swagger_auto_schema(method='post', operation_description="POST /articles/{id}/image/")
-         @detail_route(methods=['get', 'post'], parser_classes=(MultiPartParser,))
+         @action(detail=True, methods=['get', 'post'], parser_classes=(MultiPartParser,))
          def image(self, request, id=None):
             ...
 
@@ -214,7 +121,7 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
    If you want to customize the generation of a method you are not implementing yourself, you can use
    ``swagger_auto_schema`` in combination with Django's ``method_decorator``:
 
-   .. code:: python
+   .. code-block:: python
 
       @method_decorator(name='list', decorator=swagger_auto_schema(
           operation_description="description from swagger_auto_schema via method_decorator"
@@ -229,7 +136,7 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
    You can go even further and directly decorate the result of ``as_view``, in the same manner you would
    override an ``@api_view`` as described above:
 
-   .. code:: python
+   .. code-block:: python
 
       decorated_login_view = \
          swagger_auto_schema(
@@ -249,15 +156,183 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
    However, do note that both of the methods above can lead to unexpected (and maybe surprising) results by
    replacing/decorating methods on the base class itself.
 
+
+*********************************
+Support for SerializerMethodField
+*********************************
+
+Schema generation of ``serializers.SerializerMethodField`` is supported in two ways:
+
+1) The :func:`swagger_serializer_method <.swagger_serializer_method>` decorator for the use case where the serializer
+   method is using a serializer. e.g.:
+
+   .. code-block:: python
+
+      from drf_yasg.utils import swagger_serializer_method
+
+      class OtherStuffSerializer(serializers.Serializer):
+          foo = serializers.CharField()
+
+      class ParentSerializer(serializers.Serializer):
+          other_stuff = serializers.SerializerMethodField()
+
+          @swagger_serializer_method(serializer_or_field=OtherStuffSerializer)
+          def get_other_stuff(self, obj):
+              return OtherStuffSerializer().data
+
+
+   Note that the ``serializer_or_field`` parameter can accept either a subclass or an instance of ``serializers.Field``.
+
+
+2) For simple cases where the method is returning one of the supported types, `Python 3 type hinting`_ of the
+   serializer method return value can be used. e.g.:
+
+   .. code-block:: python
+
+      class SomeSerializer(serializers.Serializer):
+          some_number = serializers.SerializerMethodField()
+
+          def get_some_number(self, obj) -> float:
+              return 1.0
+
+   When return type hinting is not supported, the equivalent ``serializers.Field`` subclass can be used with
+   :func:`swagger_serializer_method <.swagger_serializer_method>`:
+
+   .. code-block:: python
+
+      class SomeSerializer(serializers.Serializer):
+          some_number = serializers.SerializerMethodField()
+
+          @swagger_serializer_method(serializer_or_field=serializers.FloatField)
+          def get_some_number(self, obj):
+              return 1.0
+
+
+********************************
+Serializer ``Meta`` nested class
+********************************
+
+You can define some per-serializer or per-field options by adding a ``Meta`` class to your ``Serializer`` or
+serializer ``Field``, e.g.:
+
+.. code-block:: python
+
+   class WhateverSerializer(Serializer):
+      ...
+
+      class Meta:
+         ... options here ...
+
+.. _swagger_schema_fields:
+
+The available options are:
+
+   * ``ref_name`` - a string which will be used as the model definition name for this serializer class; setting it to
+     ``None`` will force the serializer to be generated as an inline model everywhere it is used. If two serializers
+     have the same ``ref_name``, both their usages will be replaced with a reference to the same definition.
+     If this option is not specified, all serializers have an implicit name derived from their class name, minus any
+     ``Serializer`` suffix (e.g. ``UserSerializer`` -> ``User``, ``SerializerWithSuffix`` -> ``SerializerWithSuffix``)
+   * ``swagger_schema_fields`` - a dictionary mapping :class:`.Schema` field names to values. These attributes
+     will be set on the :class:`.Schema` object generated from the ``Serializer``. Field names must be python values,
+     which are converted to Swagger ``Schema`` attribute names according to :func:`.make_swagger_name`.
+     Attribute names and values must conform to the `OpenAPI 2.0 specification <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject>`_.
+
+Suppose you wanted to model an email using a `JSONField` to store the subject and body for performance reasons:
+
+.. code-block:: python
+
+   from django.contrib.postgres.fields import JSONField
+
+   class Email(models.Model):
+       # Store data as JSON, but the data should be made up of
+       # an object that has two properties, "subject" and "body"
+       # Example:
+       # {
+       #   "subject": "My Title",
+       #   "body": "The body of the message.",
+       # }
+       message = JSONField()
+
+To instruct ``drf-yasg`` to output an OpenAPI schema that matches this, create a custom ``JSONField``:
+
+.. code-block:: python
+
+   class EmailMessageField(serializers.JSONField):
+       class Meta:
+           swagger_schema_fields = {
+               "type": openapi.TYPE_OBJECT,
+               "title": "Email",
+               "properties": {
+                   "subject": openapi.Schema(
+                       title="Email subject",
+                       type=openapi.TYPE_STRING,
+                   ),
+                   "body": openapi.Schema(
+                       title="Email body",
+                       type=openapi.TYPE_STRING,
+                   ),
+               },
+               "required": ["subject", "body"],
+            }
+
+   class EmailSerializer(ModelSerializer):
+       class Meta:
+           model = Email
+           fields = "__all__"
+
+       message = EmailMessageField()
+
+.. Warning::
+
+   Overriding a default ``Field`` generated by a ``ModelSerializer`` will also override automatically
+   generated validators for that ``Field``.  To add ``Serializer`` validation back in manually, see the relevant
+   `DRF Validators`_ and `DRF Fields`_ documentation.
+
+   One example way to do this is to set the ``default_validators`` attribute on a field.
+
+   .. code-block:: python
+
+      class EmailMessageField(serializers.JSONField):
+         default_validators = [my_custom_email_validator]
+         ...
+
 *************************
 Subclassing and extending
 *************************
 
-For more advanced control you can subclass :class:`.SwaggerAutoSchema` - see the documentation page for a list of
-methods you can override.
+
+---------------------
+``SwaggerAutoSchema``
+---------------------
+
+For more advanced control you can subclass :class:`~.inspectors.SwaggerAutoSchema` - see the documentation page
+for a list of methods you can override.
 
 You can put your custom subclass to use by setting it on a view method using the
-:func:`@swagger_auto_schema <.swagger_auto_schema>` decorator described above.
+:ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>` decorator described above, by setting it as a
+class-level attribute named ``swagger_schema`` on the view class, or
+:ref:`globally via settings <default-class-settings>`.
+
+For example, to generate all operation IDs as camel case, you could do:
+
+.. code-block:: python
+
+   from inflection import camelize
+
+   class CamelCaseOperationIDAutoSchema(SwaggerAutoSchema):
+      def get_operation_id(self, operation_keys):
+         operation_id = super(CamelCaseOperationIDAutoSchema, self).get_operation_id(operation_keys)
+         return camelize(operation_id, uppercase_first_letter=False)
+
+
+   SWAGGER_SETTINGS = {
+      'DEFAULT_AUTO_SCHEMA_CLASS': 'path.to.CamelCaseOperationIDAutoSchema',
+      ...
+   }
+
+--------------------------
+``OpenAPISchemaGenerator``
+--------------------------
 
 If you need to control things at a higher level than :class:`.Operation` objects (e.g. overall document structure,
 vendor extensions in metadata) you can also subclass :class:`.OpenAPISchemaGenerator` - again, see the documentation
@@ -265,3 +340,113 @@ page for a list of its methods.
 
 This custom generator can be put to use by setting it as the :attr:`.generator_class` of a :class:`.SchemaView` using
 :func:`.get_schema_view`.
+
+.. _custom-spec-inspectors:
+
+---------------------
+``Inspector`` classes
+---------------------
+
+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
+:ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>` or one of the
+:ref:`related settings <default-class-settings>`.
+
+A :class:`~.inspectors.FilterInspector` that adds a description to all ``DjangoFilterBackend`` parameters could be
+implemented like so:
+
+.. code-block:: python
+
+   class DjangoFilterDescriptionInspector(CoreAPICompatInspector):
+      def get_filter_parameters(self, filter_backend):
+         if isinstance(filter_backend, DjangoFilterBackend):
+            result = super(DjangoFilterDescriptionInspector, self).get_filter_parameters(filter_backend)
+            for param in result:
+               if not param.get('description', ''):
+                  param.description = "Filter the returned list by {field_name}".format(field_name=param.name)
+
+            return result
+
+         return NotHandled
+
+   @method_decorator(name='list', decorator=swagger_auto_schema(
+      filter_inspectors=[DjangoFilterDescriptionInspector]
+   ))
+   class ArticleViewSet(viewsets.ModelViewSet):
+      filter_backends = (DjangoFilterBackend,)
+      filterset_fields = ('title',)
+      ...
+
+
+A second example, of a :class:`~.inspectors.FieldInspector` that removes the ``title`` attribute from all generated
+:class:`.Schema` objects:
+
+.. code-block:: python
+
+   class NoSchemaTitleInspector(FieldInspector):
+      def process_result(self, result, method_name, obj, **kwargs):
+         # remove the `title` attribute of all Schema objects
+         if isinstance(result, openapi.Schema.OR_REF):
+            # traverse any references and alter the Schema object in place
+            schema = openapi.resolve_ref(result, self.components)
+            schema.pop('title', None)
+
+            # no ``return schema`` here, because it would mean we always generate
+            # an inline `object` instead of a definition reference
+
+         # return back the same object that we got - i.e. a reference if we got a reference
+         return result
+
+
+   class NoTitleAutoSchema(SwaggerAutoSchema):
+      field_inspectors = [NoSchemaTitleInspector] + swagger_settings.DEFAULT_FIELD_INSPECTORS
+
+   class ArticleViewSet(viewsets.ModelViewSet):
+      swagger_schema = NoTitleAutoSchema
+      ...
+
+
+.. Note::
+
+   A note on references - :class:`.Schema` objects are sometimes output by reference (:class:`.SchemaRef`); in fact,
+   that is how named models are implemented in OpenAPI:
+
+      - in the output swagger document there is a ``definitions`` section containing :class:`.Schema` objects for all
+        models
+      - every usage of a model refers to that single :class:`.Schema` object - for example, in the ArticleViewSet
+        above, all requests and responses containg an ``Article`` model would refer to the same schema definition by a
+        ``'$ref': '#/definitions/Article'``
+
+   This is implemented by only generating **one** :class:`.Schema` object for every serializer **class** encountered.
+
+   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.
+
+   **IMPORTANT:** nested fields on ``ModelSerializer``\ s that are generated from model ``ForeignKeys`` will always be
+   output by value. If you want the by-reference behaviour you have to explictly set the serializer class of nested
+   fields instead of letting ``ModelSerializer`` generate one automatically; for example:
+
+   .. code-block:: python
+
+      class OneSerializer(serializers.ModelSerializer):
+         class Meta:
+            model = SomeModel
+            fields = ('id',)
+
+
+      class AnotherSerializer(serializers.ModelSerializer):
+         child = OneSerializer()
+
+         class Meta:
+            model = SomeParentModel
+            fields = ('id', 'child')
+
+   Another caveat that stems from this is that any serializer named "``NestedSerializer``" will be forced inline
+   unless it has a ``ref_name`` set explicitly.
+
+
+.. _Python 3 type hinting: https://docs.python.org/3/library/typing.html
+.. _DRF Validators: https://www.django-rest-framework.org/api-guide/validators/
+.. _DRF Fields: https://www.django-rest-framework.org/api-guide/fields/#validators

docs/custom_ui.rst

@@ -2,6 +2,14 @@
 Customizing the web UI
 ######################
 
-There is currently no pluggable way of customizing the web UI apart from the settings available in
-:ref:`swagger-ui-settings` and :ref:`redoc-ui-settings`. If you really need to, you can override one of the
-``drf-yasg/swagger-ui.html`` or ``drf-yasg/redoc.html`` templates that are used for rendering.
+The web UI can be customized using the settings available in :ref:`swagger-ui-settings` and :ref:`redoc-ui-settings`.
+
+You can also extend one of the `drf-yasg/swagger-ui.html`_ or `drf-yasg/redoc.html`_ templates that are used for
+rendering. See the template source code (linked above) for a complete list of customizable blocks.
+
+The ``swagger-ui`` view has some quite involed JavaScript hooks used for some functionality, which you might also
+want to review at `drf-yasg/swagger-ui-init.js`_.
+
+.. _drf-yasg/swagger-ui.html: https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/templates/drf-yasg/swagger-ui.html
+.. _drf-yasg/swagger-ui-init.js: https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/static/drf-yasg/swagger-ui-init.js
+.. _drf-yasg/redoc.html: https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/templates/drf-yasg/redoc.html

docs/drf_yasg.rst

@@ -1,14 +1,6 @@
 drf\_yasg package
 ====================
 
-drf\_yasg\.app\_settings
-----------------------------------
-
-.. automodule:: drf_yasg.app_settings
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 drf\_yasg\.codecs
 ---------------------------
 
@@ -16,7 +8,7 @@ drf\_yasg\.codecs
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: SaneYamlDumper
+    :exclude-members: SaneYamlDumper,SaneYamlLoader
 
 drf\_yasg\.errors
 ---------------------------
@@ -37,6 +29,8 @@ drf\_yasg\.generators
 drf\_yasg\.inspectors
 -------------------------------
 
+.. autodata:: drf_yasg.inspectors.NotHandled
+
 .. automodule:: drf_yasg.inspectors
     :members:
     :undoc-members:

docs/index.rst

@@ -12,6 +12,8 @@ drf-yasg
 
    readme.rst
    rendering.rst
+   openapi.rst
+   security.rst
    custom_spec.rst
    custom_ui.rst
    settings.rst

docs/openapi.rst

@@ -0,0 +1,188 @@
+.. |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>`__.
+
+Because 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>`
+* use the ``swagger_fake_view`` marker to detect requests generated by ``drf-yasg``:
+
+   .. code-block:: python
+
+     def get_serializer_class(self):
+        if getattr(self, 'swagger_fake_view', False):
+           return TodoTreeSerializer
+
+        raise NotImplementedError("must not call this")
+
+.. _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

docs/rendering.rst

@@ -2,6 +2,7 @@
 Serving the schema
 ##################
 
+
 ************************************************
 ``get_schema_view`` and the ``SchemaView`` class
 ************************************************
@@ -14,7 +15,7 @@ in the README for a usage example.
 
 You can also subclass :class:`.SchemaView` by extending the return value of :func:`.get_schema_view`, e.g.:
 
-.. code:: python
+.. code-block:: python
 
     SchemaView = get_schema_view(info, ...)
 
@@ -33,3 +34,52 @@ codec and the view.
 
 You can use your custom renderer classes as kwargs to :meth:`.SchemaView.as_cached_view` or by subclassing
 :class:`.SchemaView`.
+
+.. _management-command:
+
+******************
+Management command
+******************
+
+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:
+
+.. code-block:: console
+
+   $ python manage.py generate_swagger swagger.json
+
+See the command help for more advanced options:
+
+.. code-block:: console
+
+   $ python manage.py generate_swagger --help
+   usage: manage.py generate_swagger [-h] [--version] [-v {0,1,2,3}]
+      ... more options ...
+
+
+.. Note::
+
+   The :ref:`DEFAULT_INFO <default-swagger-settings>` setting must be defined when using the ``generate_swagger``
+   command. For example, the :ref:`README quickstart <readme-quickstart>` code could be modified as such:
+
+   In ``settings.py``:
+
+   .. code-block:: python
+
+      SWAGGER_SETTINGS = {
+         'DEFAULT_INFO': 'import.path.to.urls.api_info',
+      }
+
+   In ``urls.py``:
+
+   .. code-block:: python
+
+      api_info = openapi.Info(
+         title="Snippets API",
+         ... other arguments ...
+      )
+
+      schema_view = get_schema_view(
+         # the info argument is no longer needed here as it will be picked up from DEFAULT_INFO
+         ... other arguments ...
+      )

docs/security.rst

@@ -0,0 +1,99 @@
+*********************************
+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 any one of 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>`.
+
+
+-------------------------------
+``swagger-ui`` as OAuth2 client
+-------------------------------
+
+It is possible to configure ``swagger-ui`` to authenticate against your (or a third party) OAuth2 service when sending
+"Try it out" requests. This client-side configuration does not remove the requirement of a spec-side
+:ref:`security definiiton <security-definitions-settings>`, but merely allows you to test OAuth2 APIs using
+``swagger-ui`` as a client.
+
+**DISCLAIMER**: this setup is very poorly tested as I do not currently implement OAuth in any of my projects. All
+contributions relating to documentation, bugs, mistakes or anything else are welcome as an issue or pull request. The
+settings described below were added as a result of discussion in issue :issue:`53`.
+
+The settings of interest can be found on the :ref:`settings page <oauth2-settings>`. Configuration options are similar
+to most OAuth client setups like web or mobile applications. Reading the relevant ``swagger-ui`` docmentation linked
+will also probably help.
+
+
+Example
+^^^^^^^
+
+A very simple working configuration was provided by :ghuser:`Vigrond`, originally at
+`https://github.com/Vigrond/django_oauth2_example <https://github.com/Vigrond/django_oauth2_example>`_.
+
+
+.. code-block:: python
+
+   SWAGGER_SETTINGS = {
+      'USE_SESSION_AUTH': False,
+      'SECURITY_DEFINITIONS': {
+         'Your App API - Swagger': {
+            'type': 'oauth2',
+            'authorizationUrl': '/yourapp/o/authorize',
+            'tokenUrl': '/yourapp/o/token/',
+            'flow': 'accessCode',
+            'scopes': {
+             'read:groups': 'read groups',
+            }
+         }
+      },
+      'OAUTH2_CONFIG': {
+         'clientId': 'yourAppClientId',
+         'clientSecret': 'yourAppClientSecret',
+         'appName': 'your application name'
+      },
+   }
+
+If the OAuth2 provider requires you to provide the full absolute redirect URL, the default value for most
+``staticfiles`` configurations will be ``<origin>/static/drf-yasg/swagger-ui-dist/oauth2-redirect.html``. If this is
+not suitable for some reason, you can override the ``OAUTH2_REDIRECT_URL`` setting as appropriate.

docs/settings.rst

@@ -15,7 +15,7 @@ Example:
 
 **settings.py**
 
-.. code:: python
+.. code-block:: python
 
    SWAGGER_SETTINGS = {
        'SECURITY_DEFINITIONS': {
@@ -27,15 +27,124 @@ Example:
    }
 
    REDOC_SETTINGS = {
-      'LAZY_RENDERING': True,
+      'LAZY_RENDERING': False,
       ...
    }
 
+.. _url-settings:
+
+All settings which configure URLs (``LOGIN_URL``, ``SPEC_URL``, ``VALIDATOR_URL``, etc.) can accept several forms of
+input:
+
+* A view name: `urls.reverse()` will be used to reverse-resolve the name
+* A 2-tuple of ``(view_name, kwargs)```: `urls.reverse()` will be used to reverse-resolve the name using the given
+  `kwargs`; `kwargs` must be a dict
+* A 3-tuple of ``(view_name, args, kwargs)```: `urls.reverse()` will be used to reverse-resolve the name using the given
+  `args` and `kwargs`; `args`, `kwargs` must be a tuple/list and a dict respectively
+* A URL, which will be used as-is
+
 The possible settings and their default values are as follows:
 
-********************
-``SWAGGER_SETTINGS``
-********************
+****************
+SWAGGER_SETTINGS
+****************
+
+.. _default-class-settings:
+
+Default classes
+===============
+
+DEFAULT_GENERATOR_CLASS
+-------------------------
+
+:class:`~.generators.OpenAPISchemaGenerator` subclass that will be used by default for generating the final
+:class:`.Schema` object. Can be overriden by the ``generator_class`` argument to :func:`.get_schema_view`.
+
+**Default**: :class:`drf_yasg.generators.OpenAPISchemaGenerator`
+
+DEFAULT_AUTO_SCHEMA_CLASS
+-------------------------
+
+:class:`~.inspectors.ViewInspector` subclass that will be used by default for generating :class:`.Operation`
+objects when iterating over endpoints. Can be overriden by using the `auto_schema` argument of
+:func:`@swagger_auto_schema <.swagger_auto_schema>` or by a ``swagger_schema`` attribute on the view class.
+
+**Default**: :class:`drf_yasg.inspectors.SwaggerAutoSchema`
+
+DEFAULT_FIELD_INSPECTORS
+------------------------
+
+List of :class:`~.inspectors.FieldInspector` subclasses that will be used by default for inspecting serializers and
+serializer fields. Field inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended
+to this list.
+
+**Default**: ``[``  |br| \
+:class:`'drf_yasg.inspectors.CamelCaseJSONFilter' <.inspectors.CamelCaseJSONFilter>`, |br| \
+:class:`'drf_yasg.inspectors.ReferencingSerializerInspector' <.inspectors.ReferencingSerializerInspector>`, |br| \
+:class:`'drf_yasg.inspectors.RelatedFieldInspector' <.inspectors.RelatedFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.ChoiceFieldInspector' <.inspectors.ChoiceFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.FileFieldInspector' <.inspectors.FileFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.DictFieldInspector' <.inspectors.DictFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.JSONFieldInspector' <.inspectors.JSONFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.HiddenFieldInspector' <.inspectors.HiddenFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.RecursiveFieldInspector' <.inspectors.RecursiveFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.SerializerMethodFieldInspector' <.inspectors.SerializerMethodFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.SimpleFieldInspector' <.inspectors.SimpleFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.StringDefaultFieldInspector' <.inspectors.StringDefaultFieldInspector>`, |br| \
+``]``
+
+DEFAULT_FILTER_INSPECTORS
+-------------------------
+
+List of :class:`~.inspectors.FilterInspector` subclasses that will be used by default for inspecting filter backends.
+Filter inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended to this list.
+
+**Default**: ``[``  |br| \
+:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`, |br| \
+``]``
+
+DEFAULT_PAGINATOR_INSPECTORS
+----------------------------
+
+List of :class:`~.inspectors.PaginatorInspector` subclasses that will be used by default for inspecting paginators.
+Paginator inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>` will be prepended to this list.
+
+**Default**: ``[``  |br| \
+:class:`'drf_yasg.inspectors.DjangoRestResponsePagination' <.inspectors.DjangoRestResponsePagination>`, |br| \
+:class:`'drf_yasg.inspectors.CoreAPICompatInspector' <.inspectors.CoreAPICompatInspector>`, |br| \
+``]``
+
+Swagger document attributes
+===========================
+
+EXCLUDED_MEDIA_TYPES
+--------------------
+
+A list of keywords for excluding MIME types from ``Operation.produces``. Any MIME type string which includes one of
+the substrings in this list will be prevented from appearing in a ``produces`` array in the Swagger document.
+
+**Default**: :python:`['html']`
+
+.. _default-swagger-settings:
+
+DEFAULT_INFO
+------------
+
+An import string to an :class:`.openapi.Info` object. This will be used when running the ``generate_swagger``
+management command, or if no ``info`` argument is passed to :func:`.get_schema_view`.
+
+**Default**: :python:`None`
+
+DEFAULT_API_URL
+---------------
+
+A string representing the default API URL. This will be used to populate the ``host`` and ``schemes`` attributes
+of the Swagger document if no API URL is otherwise provided. The Django `FORCE_SCRIPT_NAME`_ setting can be used for
+providing an API mount point prefix.
+
+See also: :ref:`documentation on base URL construction <custom-spec-base-url>`
+
+**Default**: :python:`None`
 
 Authorization
 =============
@@ -62,6 +171,9 @@ URL for the Django Logout action when using `USE_SESSION_AUTH`_.
 
 **Default**: :python:`django.conf.settings.LOGOUT_URL`
 
+.. _security-definitions-settings:
+
+
 SECURITY_DEFINITIONS
 --------------------
 
@@ -70,12 +182,20 @@ See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#sec
 
 **Default**:
 
-.. code:: python
+.. code-block:: python
 
    'basic': {
       '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
@@ -84,6 +204,15 @@ Swagger UI settings
 Swagger UI configuration settings. |br|
 See https://github.com/swagger-api/swagger-ui/blob/112bca906553a937ac67adc2e500bdeed96d067b/docs/usage/configuration.md#parameters.
 
+SPEC_URL
+--------
+
+URL pointing to a swagger document for use by swagger-ui. The default behaviour is to append ``?format=openapi`` to the
+URL which serves the UI; see :ref:`note on URL settings <url-settings>` above.
+
+**Default**: :python:`None` |br|
+*Maps to parameter*: ``url``
+
 VALIDATOR_URL
 -------------
 
@@ -94,14 +223,48 @@ set to ``None`` to remove the badge.
 **Default**: :python:`'http://online.swagger.io/validator/'` |br|
 *Maps to parameter*: ``validatorUrl``
 
+PERSIST_AUTH
+------------
+
+Persist swagger-ui authorization data to local storage. |br|
+**WARNING:** This may be a security risk as the credentials are stored unencrypted and can be accessed
+by all javascript code running on the same domain.
+
+**Default**: :python:`False` |br|
+*Maps to parameter*: -
+
+REFETCH_SCHEMA_WITH_AUTH
+------------------------
+
+Re-fetch the OpenAPI document with the new credentials after authorization is performed through swagger-ui.
+
+**Default**: :python:`False` |br|
+*Maps to parameter*: -
+
+REFETCH_SCHEMA_ON_LOGOUT
+------------------------
+
+Re-fetch the OpenAPI document without credentials after authorization is removed through swagger-ui.
+
+**Default**: :python:`False` |br|
+*Maps to parameter*: -
+
+FETCH_SCHEMA_WITH_QUERY
+-----------------------
+
+Fetch the OpenAPI document using the query parameters passed to the swagger-ui page request.
+
+**Default**: :python:`True` |br|
+*Maps to parameter*: -
+
 OPERATIONS_SORTER
 -----------------
 
 Sorting order for the operation list of each tag.
 
 * :python:`None`: show in the order returned by the server
-* :python:`alpha`: sort alphabetically by path
-* :python:`method`: sort by HTTP method
+* :python:`'alpha'`: sort alphabetically by path
+* :python:`'method'`: sort by HTTP method
 
 **Default**: :python:`None` |br|
 *Maps to parameter*: ``operationsSorter``
@@ -112,7 +275,7 @@ TAGS_SORTER
 Sorting order for tagged operation groups.
 
 * :python:`None`: Swagger UI default ordering
-* :python:`alpha`: sort alphabetically
+* :python:`'alpha'`: sort alphabetically
 
 **Default**: :python:`None` |br|
 *Maps to parameter*: ``tagsSorter``
@@ -122,9 +285,9 @@ DOC_EXPANSION
 
 Controls the default expansion setting for the operations and tags.
 
-* :python:`None`: everything is collapsed
-* :python:`list`: only tags are expanded
-* :python:`full`: all operations are expanded
+* :python:`'none'`: everything is collapsed
+* :python:`'list'`: only tags are expanded
+* :python:`'full'`: all operations are expanded
 
 **Default**: :python:`'list'` |br|
 *Maps to parameter*: ``docExpansion``
@@ -150,8 +313,8 @@ DEFAULT_MODEL_RENDERING
 
 Controls whether operations show the model structure or the example value by default.
 
-* :python:`model`: show the model fields by default
-* :python:`example`: show the example value by default
+* :python:`'model'`: show the model fields by default
+* :python:`'example'`: show the example value by default
 
 **Default**: :python:`'model'` |br|
 *Maps to parameter*: ``defaultModelRendering``
@@ -164,9 +327,57 @@ Controls how many levels are expaned by default when showing nested models.
 **Default**: :python:`3` |br|
 *Maps to parameter*: ``defaultModelExpandDepth``
 
-******************
-``REDOC_SETTINGS``
-******************
+SHOW_COMMON_EXTENSIONS
+----------------------
+
+Controls the display of extensions (``pattern``, ``maxLength``, ``minLength``, ``maximum``, ``minimum``) fields and
+values for Parameters.
+
+**Default**: :python:`True` |br|
+*Maps to parameter*: ``showCommonExtensions``
+
+.. _oauth2-settings:
+
+OAUTH2_REDIRECT_URL
+-------------------
+
+Used when OAuth2 authentication of API requests via swagger-ui is desired. If ``None`` is passed, the
+``oauth2RedirectUrl`` parameter will be set to ``{% static 'drf-yasg/swagger-ui-dist/oauth2-redirect.html' %}``. This
+is the default `https://github.com/swagger-api/swagger-ui/blob/master/dist/oauth2-redirect.html <oauth2-redirect>`_
+file provided by ``swagger-ui``.
+
+**Default**: :python:`None` |br|
+*Maps to parameter*: ``oauth2RedirectUrl``
+
+OAUTH2_CONFIG
+-------------
+
+Used when OAuth2 authentication of API requests via swagger-ui is desired. Provides OAuth2 configuration parameters
+to the ``SwaggerUIBundle#initOAuth`` method, and must be a dictionary. See
+`OAuth2 configuration <https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md>`_.
+
+**Default**: :python:`{}`
+
+SUPPORTED_SUBMIT_METHODS
+------------------------
+
+List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations.
+This does not filter the operations from the display.
+
+**Default**: :python:`['get','put','post','delete','options','head','patch','trace']` |br|
+*Maps to parameter*: ``supportedSubmitMethods``
+
+DISPLAY_OPERATION_ID
+--------------------
+
+Controls the display of operationId in operations list.
+
+**Default**: :python:`True`
+*Maps to parameter*: ``displayOperationId``
+
+**************
+REDOC_SETTINGS
+**************
 
 .. _redoc-ui-settings:
 
@@ -174,28 +385,78 @@ ReDoc UI settings
 =================
 
 ReDoc UI configuration settings. |br|
-See https://github.com/Rebilly/ReDoc#redoc-tag-attributes.
+See https://github.com/Rebilly/ReDoc#configuration.
+
+SPEC_URL
+--------
+
+URL pointing to a swagger document for use by ReDoc. The default behaviour is to append ``?format=openapi`` to the
+URL which serves the UI; see :ref:`note on URL settings <url-settings>` above.
+
+**Default**: :python:`None` |br|
+*Maps to attribute*: ``spec-url``
 
 LAZY_RENDERING
 --------------
 
-**Default**: :python:`True` |br|
-*Maps to attribute*: ``lazy-rendering``
+If set, enables lazy rendering mode in ReDoc. This mode is useful for APIs with big number of operations (e.g. > 50).
+In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing
+progress bar on the top.
+
+**NOTE:** this feature might be removed in future versions of ReDoc (see https://github.com/Rebilly/ReDoc/issues/475)
+
+**Default**: :python:`False` |br|
+*Maps to attribute*: ``lazyRendering``
 
 HIDE_HOSTNAME
 -------------
 
+If set, the protocol and hostname is not shown in the operation definition.
+
 **Default**: :python:`False` |br|
-*Maps to attribute*: ``hide-hostname``
+*Maps to attribute*: ``hideHostname``
 
 EXPAND_RESPONSES
 ----------------
 
+Specify which responses to expand by default by response codes. Values should be passed as comma-separated list without
+spaces e.g. expandResponses="200,201". Special value "all" expands all responses by default.
+Be careful: this option can slow-down documentation rendering time.
+
 **Default**: :python:`'all'` |br|
-*Maps to attribute*: ``expand-responses``
+*Maps to attribute*: ``expandResponses``
 
 PATH_IN_MIDDLE
 --------------
 
+Show path link and HTTP verb in the middle panel instead of the right one.
+
 **Default**: :python:`False` |br|
-*Maps to attribute*: ``path-in-middle-panel``
+*Maps to attribute*: ``pathInMiddlePanel``
+
+NATIVE_SCROLLBARS
+-----------------
+
+Use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).
+
+**Default**: :python:`False` |br|
+*Maps to attribute*: ``nativeScrollbars``
+
+REQUIRED_PROPS_FIRST
+--------------------
+
+Show required properties first ordered in the same order as in required array.
+
+**Default**: :python:`False` |br|
+*Maps to attribute*: ``requiredPropsFirst``
+
+FETCH_SCHEMA_WITH_QUERY
+-----------------------
+
+Fetch the OpenAPI document using the query parameters passed to the ReDoc page request.
+
+**Default**: :python:`True` |br|
+*Maps to parameter*: -
+
+
+.. _FORCE_SCRIPT_NAME: https://docs.djangoproject.com/en/2.0/ref/settings/#force-script-name

package.json

@@ -1,7 +1,12 @@
 {
   "name": "drf-yasg",
   "dependencies": {
-    "redoc": "^1.19.3",
-    "swagger-ui-dist": "^3.8.0"
-  }
+    "redoc": "^2.0.0-rc.14",
+    "swagger-ui-dist": "^3.23.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axnsan12/drf-yasg.git"
+  },
+  "private": true
 }

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools >= 40.6.3", "wheel", "setuptools-scm >= 3.0.3"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,4 @@
+# this file is only used when deploying to heroku, because heroku insists on having a root-level requirements.txt
+# for normal usage see the requirements/ directory
+.[validation]
+-r requirements/heroku.txt

requirements/base.txt

@@ -1,6 +1,10 @@
 coreapi>=2.3.3
 coreschema>=0.0.4
-openapi_codec>=1.3.2
 ruamel.yaml>=0.15.34
 inflection>=0.3.1
-future>=0.16.0
+six>=1.10.0
+uritemplate>=3.0.0
+packaging
+
+djangorestframework>=3.8
+Django>=1.11.7

requirements/ci.txt

@@ -1,4 +1,5 @@
-# requirements for CI test suite
--r dev.txt
+# requirements for the CI test runner
 tox-travis>=0.10
 codecov>=2.0.9
+
+-r tox.txt

requirements/dev.txt

@@ -1,6 +1,7 @@
-# requirements for local development
-tox>=2.9.1
-tox-battery>=0.5
+# requirements for local development to be installed via pip install -U -r requirements/dev.txt
+-r tox.txt
+-r test.txt
+-r lint.txt
 
-# do not unpin this (see setup.py)
-setuptools_scm==1.15.6
+tox-battery>=0.5
+django-oauth-toolkit

requirements/docs.txt

@@ -1,6 +1,9 @@
-Sphinx==1.6.5
-sphinx_rtd_theme==0.2.4
-Pillow==4.3.0
-readme_renderer==17.2
+# used by the 'docs' tox env for building the documentation
+Sphinx>=1.7.0
+sphinx_rtd_theme>=0.2.4
+Pillow>=4.3.0
+readme_renderer[md]>=24.0
+twine>=1.12.1
 
-Django==2.0
+Django>=2.0
+djangorestframework_camel_case>=0.2.0

requirements/heroku.txt

@@ -0,0 +1,5 @@
+# requirements necessary when deploying the test project to heroku
+-r testproj.txt
+psycopg2>=2.7.3
+gunicorn>=19.7.1
+whitenoise>=3.3.1

requirements/lint.txt

@@ -0,0 +1,4 @@
+# used by the 'lint' tox env for linting via flake8
+isort>=4.2
+flake8>=3.5.0
+flake8-isort>=2.3

requirements/test.txt

@@ -1,14 +1,11 @@
-# pytest runner + plugins
-pytest>=2.9
+# requirements for running the tests via pytest
+pytest>=4.0
 pytest-pythonpath>=0.7.1
-pytest-cov>=2.5.1
-# latest pip version of pytest-django is more than a year old and does not support Django 2.0
-git+https://github.com/pytest-dev/pytest-django.git@94cccb956435dd7a719606744ee7608397e1eafb
+pytest-cov>=2.6.0
+pytest-xdist>=1.25.0
+pytest-django>=3.4.4
 datadiff==2.0.0
+psycopg2-binary==2.8.3
+django-fake-model==0.1.4
 
-# test project requirements
-Pillow>=4.3.0
-pygments>=2.2.0
-django-cors-headers>=2.1.0
-django-filter>=1.1.0,<2.0; python_version == "2.7"
-django-filter>=1.1.0; python_version >= "3.4"
+-r testproj.txt

requirements/testproj.txt

@@ -0,0 +1,9 @@
+# test project requirements
+Pillow>=4.3.0
+django-filter>=1.1.0,<2.0; python_version == "2.7"
+django-filter>=1.1.0; python_version >= "3.5"
+djangorestframework-camel-case>=1.1.2
+djangorestframework-recursive>=0.1.2
+dj-database-url>=0.4.2
+user_agents>=1.1.0
+django-cors-headers

requirements/tox.txt

@@ -0,0 +1,2 @@
+# requirements for building and running tox
+tox>=3.3.0

requirements/validation.txt

@@ -1,3 +1,2 @@
 # requirements for the validation feature
-flex>=6.11.1
 swagger-spec-validator>=2.1.0

runtime.txt

@@ -0,0 +1 @@
+python-3.7.3

setup.cfg

@@ -0,0 +1,5 @@
+[bdist_wheel]
+universal = 1
+
+[metadata]
+license_file = LICENSE.rst

setup.py

@@ -1,94 +1,96 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+from __future__ import print_function
+
 import io
 import os
-
 import sys
-from setuptools import setup, find_packages
-import distutils.core
-
-requirements_setup = ['setuptools_scm==1.15.6']
-
-
-def _install_setup_requires(attrs):
-    # copied from setuptools
-    dist = distutils.core.Distribution(dict(
-        (k, v) for k, v in attrs.items()
-        if k in ('dependency_links', 'setup_requires')
-    ))
-    # Honor setup.cfg's options.
-    dist.parse_config_files(ignore_option_errors=True)
-    if dist.setup_requires:
-        dist.fetch_build_eggs(dist.setup_requires)
-
-
-if 'sdist' in sys.argv:
-    try:
-        # try to install setuptools_scm before setuptools does it, otherwise our monkey patch below will come too early
-        # (setuptools_scm adds find_files hooks into setuptools on install)
-        _install_setup_requires({'setup_requires': requirements_setup})
-    except Exception:
-        pass
-
-    try:
-        # see https://github.com/pypa/setuptools_scm/issues/190, setuptools_scm includes ALL versioned files from
-        # the git repo into the sdist by default, and there is no easy way to provide an opt-out;
-        # this hack is ugly but does the job; because this is not really a documented interface of the module,
-        # the setuptools_scm version should remain pinned to ensure it keeps working
-        import setuptools_scm.integration
-
-        setuptools_scm.integration.find_files = lambda _: []
-    except ImportError:
-        pass
+from setuptools import find_packages, setup
 
 
 def read_req(req_file):
     with open(os.path.join('requirements', req_file)) as req:
-        return [line for line in req.readlines() if line and not line.isspace()]
+        return [line.strip() for line in req.readlines() if line.strip() and not line.strip().startswith('#')]
 
 
 with io.open('README.rst', encoding='utf-8') as readme:
     description = readme.read()
 
-requirements = ['djangorestframework>=3.7.0'] + read_req('base.txt')
+requirements = read_req('base.txt')
 requirements_validation = read_req('validation.txt')
 
-setup(
-    name='drf-yasg',
-    use_scm_version=True,
-    packages=find_packages('src', include=['drf_yasg']),
-    package_dir={'': 'src'},
-    include_package_data=True,
-    install_requires=requirements,
-    setup_requires=requirements_setup,
-    extras_require={
-        'validation': requirements_validation,
-    },
-    license='BSD License',
-    description='Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.',
-    long_description=description,
-    url='https://github.com/axnsan12/drf-yasg',
-    author='Cristi V.',
-    author_email='cristi@cvjd.me',
-    keywords='drf django django-rest-framework schema swagger openapi codegen swagger-codegen '
-             'documentation drf-yasg django-rest-swagger drf-openapi',
-    classifiers=[
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: BSD License',
-        'Development Status :: 4 - Beta',
-        'Operating System :: OS Independent',
-        'Environment :: Web Environment',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 2',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.4',
-        'Programming Language :: Python :: 3.5',
-        'Programming Language :: Python :: 3.6',
-        'Framework :: Django',
-        'Framework :: Django :: 1.11',
-        'Framework :: Django :: 2.0',
-        'Topic :: Documentation',
-        'Topic :: Software Development :: Code Generators',
-    ],
-)
+py3_supported_range = (5, 8)
+
+# convert inclusive range to exclusive range
+py3_supported_range = (py3_supported_range[0], py3_supported_range[1] + 1)
+python_requires = ", ".join([">=2.7"] + ["!=3.{}.*".format(v) for v in range(0, py3_supported_range[0])])
+python_classifiers = [
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 2',
+    'Programming Language :: Python :: 2.7',
+    'Programming Language :: Python :: 3',
+] + ['Programming Language :: Python :: 3.{}'.format(v) for v in range(*py3_supported_range)]
+
+
+def drf_yasg_setup(**kwargs):
+    setup(
+        name='drf-yasg',
+        packages=find_packages('src'),
+        package_dir={'': 'src'},
+        include_package_data=True,
+        install_requires=requirements,
+        extras_require={
+            'validation': requirements_validation,
+        },
+        license='BSD License',
+        description='Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.',
+        long_description=description,
+        url='https://github.com/axnsan12/drf-yasg',
+        author='Cristi V.',
+        author_email='cristi@cvjd.me',
+        keywords='drf django django-rest-framework schema swagger openapi codegen swagger-codegen '
+                 'documentation drf-yasg django-rest-swagger drf-openapi',
+        python_requires=python_requires,
+        classifiers=[
+            'Intended Audience :: Developers',
+            'License :: OSI Approved :: BSD License',
+            'Development Status :: 5 - Production/Stable',
+            'Operating System :: OS Independent',
+            'Environment :: Web Environment',
+            'Framework :: Django',
+            'Framework :: Django :: 1.11',
+            'Framework :: Django :: 2.0',
+            'Framework :: Django :: 2.1',
+            'Framework :: Django :: 2.2',
+            'Topic :: Documentation',
+            'Topic :: Software Development :: Code Generators',
+        ] + python_classifiers,
+        **kwargs
+    )
+
+
+try:
+    # noinspection PyUnresolvedReferences
+    import setuptools_scm  # noqa: F401
+
+    drf_yasg_setup(use_scm_version=True)
+except (ImportError, LookupError) as e:
+    if os.getenv('CI', 'false') == 'true' or os.getenv('TRAVIS', 'false') == 'true':
+        # don't silently fail on travis - we don't want to accidentally push a dummy version to PyPI
+        raise
+
+    err_msg = str(e)
+    if 'setuptools-scm' in err_msg or 'setuptools_scm' in err_msg:
+        import time
+        import traceback
+
+        timestamp_ms = int(time.time() * 1000)
+        timestamp_str = hex(timestamp_ms)[2:].zfill(16)
+        dummy_version = '1!0.0.0.dev0+noscm.' + timestamp_str
+
+        drf_yasg_setup(version=dummy_version)
+
+        traceback.print_exc(file=sys.stderr)
+        print("failed to detect version, package was built with dummy version " + dummy_version, file=sys.stderr)
+    else:
+        raise

src/drf_yasg/__init__.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-from pkg_resources import get_distribution, DistributionNotFound
+from pkg_resources import DistributionNotFound, get_distribution
 
 __author__ = """Cristi V."""
 __email__ = 'cristi@cvjd.me'

src/drf_yasg/app_settings.py

@@ -2,15 +2,51 @@ from django.conf import settings
 from rest_framework.settings import perform_import
 
 SWAGGER_DEFAULTS = {
+    'DEFAULT_GENERATOR_CLASS': 'drf_yasg.generators.OpenAPISchemaGenerator',
+    'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
+
+    'DEFAULT_FIELD_INSPECTORS': [
+        'drf_yasg.inspectors.CamelCaseJSONFilter',
+        'drf_yasg.inspectors.RecursiveFieldInspector',
+        'drf_yasg.inspectors.ReferencingSerializerInspector',
+        'drf_yasg.inspectors.ChoiceFieldInspector',
+        'drf_yasg.inspectors.FileFieldInspector',
+        'drf_yasg.inspectors.DictFieldInspector',
+        'drf_yasg.inspectors.JSONFieldInspector',
+        'drf_yasg.inspectors.HiddenFieldInspector',
+        'drf_yasg.inspectors.RelatedFieldInspector',
+        'drf_yasg.inspectors.SerializerMethodFieldInspector',
+        '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',
+    ],
+
+    'EXCLUDED_MEDIA_TYPES': ['html'],
+
+    'DEFAULT_INFO': None,
+    'DEFAULT_API_URL': None,
+
     'USE_SESSION_AUTH': True,
     'SECURITY_DEFINITIONS': {
-        'basic': {
+        'Basic': {
             'type': 'basic'
         }
     },
+    'SECURITY_REQUIREMENTS': None,
     'LOGIN_URL': getattr(settings, 'LOGIN_URL', None),
     'LOGOUT_URL': getattr(settings, 'LOGOUT_URL', None),
+    'SPEC_URL': None,
     'VALIDATOR_URL': '',
+    'PERSIST_AUTH': False,
+    'REFETCH_SCHEMA_WITH_AUTH': False,
+    'REFETCH_SCHEMA_ON_LOGOUT': False,
+    'FETCH_SCHEMA_WITH_QUERY': True,
 
     'OPERATIONS_SORTER': None,
     'TAGS_SORTER': None,
@@ -19,16 +55,41 @@ SWAGGER_DEFAULTS = {
     'SHOW_EXTENSIONS': True,
     'DEFAULT_MODEL_RENDERING': 'model',
     'DEFAULT_MODEL_DEPTH': 3,
+    'SHOW_COMMON_EXTENSIONS': True,
+    'OAUTH2_REDIRECT_URL': None,
+    'OAUTH2_CONFIG': {},
+    'SUPPORTED_SUBMIT_METHODS': [
+        'get',
+        'put',
+        'post',
+        'delete',
+        'options',
+        'head',
+        'patch',
+        'trace'
+    ],
+    'DISPLAY_OPERATION_ID': True,
 }
 
 REDOC_DEFAULTS = {
-    'LAZY_RENDERING': True,
+    'SPEC_URL': None,
+    'LAZY_RENDERING': False,
     'HIDE_HOSTNAME': False,
     'EXPAND_RESPONSES': 'all',
     'PATH_IN_MIDDLE': False,
+    'NATIVE_SCROLLBARS': False,
+    'REQUIRED_PROPS_FIRST': False,
+    'FETCH_SCHEMA_WITH_QUERY': True,
 }
 
-IMPORT_STRINGS = []
+IMPORT_STRINGS = [
+    'DEFAULT_GENERATOR_CLASS',
+    'DEFAULT_AUTO_SCHEMA_CLASS',
+    'DEFAULT_FIELD_INSPECTORS',
+    'DEFAULT_FILTER_INSPECTORS',
+    'DEFAULT_PAGINATOR_INSPECTORS',
+    'DEFAULT_INFO',
+]
 
 
 class AppSettings(object):

src/drf_yasg/codecs.py

@@ -1,32 +1,39 @@
+from six import binary_type, raise_from, text_type
+
 import copy
 import json
+import logging
 from collections import OrderedDict
 
 from coreapi.compat import force_bytes
-from future.utils import raise_from
 from ruamel import yaml
 
 from . import openapi
-from .app_settings import swagger_settings
 from .errors import SwaggerValidationError
 
+logger = logging.getLogger(__name__)
+
+
+def _validate_flex(spec):
+    try:
+        from flex.core import parse as validate_flex
+        from flex.exceptions import ValidationError
+    except ImportError:
+        return
 
-def _validate_flex(spec, codec):
-    from flex.core import parse as validate_flex
-    from flex.exceptions import ValidationError
     try:
         validate_flex(spec)
     except ValidationError as ex:
-        raise_from(SwaggerValidationError(str(ex), 'flex', spec, codec), ex)
+        raise_from(SwaggerValidationError(str(ex)), ex)
 
 
-def _validate_swagger_spec_validator(spec, codec):
+def _validate_swagger_spec_validator(spec):
     from swagger_spec_validator.validator20 import validate_spec as validate_ssv
     from swagger_spec_validator.common import SwaggerValidationError as SSVErr
     try:
         validate_ssv(spec)
     except SSVErr as ex:
-        raise_from(SwaggerValidationError(str(ex), 'swagger_spec_validator', spec, codec), ex)
+        raise_from(SwaggerValidationError(str(ex)), ex)
 
 
 #:
@@ -60,10 +67,20 @@ class _OpenAPICodec(object):
             raise TypeError('Expected a `openapi.Swagger` instance')
 
         spec = self.generate_swagger_object(document)
+        errors = {}
         for validator in self.validators:
-            # validate a deepcopy of the spec to prevent the validator from messing with it
-            # for example, swagger_spec_validator adds an x-scope property to all references
-            VALIDATORS[validator](copy.deepcopy(spec), self)
+            try:
+                # validate a deepcopy of the spec to prevent the validator from messing with it
+                # for example, swagger_spec_validator adds an x-scope property to all references
+                VALIDATORS[validator](copy.deepcopy(spec))
+            except SwaggerValidationError as e:
+                errors[validator] = str(e)
+
+        if errors:
+            exc = SwaggerValidationError("spec validation failed: {}".format(errors), errors, spec, self)
+            logger.warning(str(exc))
+            raise exc
+
         return force_bytes(self._dump_dict(spec))
 
     def encode_error(self, err):
@@ -75,7 +92,7 @@ class _OpenAPICodec(object):
 
         :param dict spec: a python dict
         :return: string representation of ``spec``
-        :rtype: str
+        :rtype: str or bytes
         """
         raise NotImplementedError("override this method")
 
@@ -86,16 +103,31 @@ class _OpenAPICodec(object):
         :return: swagger spec as dict
         :rtype: OrderedDict
         """
-        swagger.security_definitions = swagger_settings.SECURITY_DEFINITIONS
         return swagger.as_odict()
 
 
 class OpenAPICodecJson(_OpenAPICodec):
     media_type = 'application/json'
 
+    def __init__(self, validators, pretty=False, media_type='application/json'):
+        super(OpenAPICodecJson, self).__init__(validators)
+        self.pretty = pretty
+        self.media_type = media_type
+
     def _dump_dict(self, spec):
-        """Dump ``spec`` into JSON."""
-        return json.dumps(spec)
+        """Dump ``spec`` into JSON.
+
+        :rtype: str"""
+        if self.pretty:
+            out = json.dumps(spec, indent=4, separators=(',', ': '))
+            if out[-1] != '\n':
+                out += '\n'
+            return out
+        else:
+            return json.dumps(spec)
+
+
+YAML_MAP_TAG = u'tag:yaml.org,2002:map'
 
 
 class SaneYamlDumper(yaml.SafeDumper):
@@ -112,8 +144,7 @@ class SaneYamlDumper(yaml.SafeDumper):
         """
         return super(SaneYamlDumper, self).increase_indent(flow=flow, indentless=False, **kwargs)
 
-    @staticmethod
-    def represent_odict(dump, mapping, flow_style=None):  # pragma: no cover
+    def represent_odict(self, mapping, flow_style=None):  # pragma: no cover
         """https://gist.github.com/miracle2k/3184458
 
         Make PyYAML output an OrderedDict.
@@ -122,30 +153,37 @@ class SaneYamlDumper(yaml.SafeDumper):
 
         To use yaml.safe_dump(), you need the following.
         """
-        tag = u'tag:yaml.org,2002:map'
+        tag = YAML_MAP_TAG
         value = []
         node = yaml.MappingNode(tag, value, flow_style=flow_style)
-        if dump.alias_key is not None:
-            dump.represented_objects[dump.alias_key] = node
+        if self.alias_key is not None:
+            self.represented_objects[self.alias_key] = node
         best_style = True
         if hasattr(mapping, 'items'):
             mapping = mapping.items()
         for item_key, item_value in mapping:
-            node_key = dump.represent_data(item_key)
-            node_value = dump.represent_data(item_value)
+            node_key = self.represent_data(item_key)
+            node_value = self.represent_data(item_value)
             if not (isinstance(node_key, yaml.ScalarNode) and not node_key.style):
                 best_style = False
             if not (isinstance(node_value, yaml.ScalarNode) and not node_value.style):
                 best_style = False
             value.append((node_key, node_value))
         if flow_style is None:
-            if dump.default_flow_style is not None:
-                node.flow_style = dump.default_flow_style
+            if self.default_flow_style is not None:
+                node.flow_style = self.default_flow_style
             else:
                 node.flow_style = best_style
         return node
 
+    def represent_text(self, text):
+        if "\n" in text:
+            return self.represent_scalar('tag:yaml.org,2002:str', text, style='|')
+        return self.represent_scalar('tag:yaml.org,2002:str', text)
 
+
+SaneYamlDumper.add_representer(binary_type, SaneYamlDumper.represent_text)
+SaneYamlDumper.add_representer(text_type, SaneYamlDumper.represent_text)
 SaneYamlDumper.add_representer(OrderedDict, SaneYamlDumper.represent_odict)
 SaneYamlDumper.add_multi_representer(OrderedDict, SaneYamlDumper.represent_odict)
 
@@ -158,17 +196,41 @@ def yaml_sane_dump(data, binary):
         * list elements are indented into their parents
         * YAML references/aliases are disabled
 
-    :param dict data: the data to be serializers
+    :param dict data: the data to be dumped
     :param bool binary: True to return a utf-8 encoded binary object, False to return a string
     :return: the serialized YAML
-    :rtype: str,bytes
+    :rtype: str or bytes
     """
     return yaml.dump(data, Dumper=SaneYamlDumper, default_flow_style=False, encoding='utf-8' if binary else None)
 
 
+class SaneYamlLoader(yaml.SafeLoader):
+    def construct_odict(self, node, deep=False):
+        self.flatten_mapping(node)
+        return OrderedDict(self.construct_pairs(node))
+
+
+SaneYamlLoader.add_constructor(YAML_MAP_TAG, SaneYamlLoader.construct_odict)
+
+
+def yaml_sane_load(stream):
+    """Load the given YAML stream while preserving the input order for mapping items.
+
+    :param stream: YAML stream (can be a string or a file-like object)
+    :rtype: OrderedDict
+    """
+    return yaml.load(stream, Loader=SaneYamlLoader)
+
+
 class OpenAPICodecYaml(_OpenAPICodec):
     media_type = 'application/yaml'
 
+    def __init__(self, validators, media_type='application/yaml'):
+        super(OpenAPICodecYaml, self).__init__(validators)
+        self.media_type = media_type
+
     def _dump_dict(self, spec):
-        """Dump ``spec`` into YAML."""
+        """Dump ``spec`` into YAML.
+
+        :rtype: bytes"""
         return yaml_sane_dump(spec, binary=True)

src/drf_yasg/errors.py

@@ -3,9 +3,9 @@ class SwaggerError(Exception):
 
 
 class SwaggerValidationError(SwaggerError):
-    def __init__(self, msg, validator_name, spec, source_codec, *args):
+    def __init__(self, msg, errors=None, spec=None, source_codec=None, *args):
         super(SwaggerValidationError, self).__init__(msg, *args)
-        self.validator_name = validator_name
+        self.errors = errors
         self.spec = spec
         self.source_codec = source_codec
 

src/drf_yasg/generators.py

@@ -1,21 +1,135 @@
+import copy
+import logging
 import re
-from collections import defaultdict, OrderedDict
+from collections import OrderedDict, defaultdict
 
+import rest_framework
 import uritemplate
-from rest_framework.schemas.generators import SchemaGenerator, EndpointEnumerator as _EndpointEnumerator
+from coreapi.compat import urlparse
+from packaging.version import Version
+from rest_framework import versioning
+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 endpoint_ordering, get_pk_name
+from rest_framework.settings import api_settings
 
 from . import openapi
-from .inspectors import SwaggerAutoSchema
-from .openapi import ReferenceResolver
-from .utils import inspect_model_field, get_model_field
+from .app_settings import swagger_settings
+from .errors import SwaggerGenerationError
+from .inspectors.field import get_basic_type_info, get_queryset_field, get_queryset_from_view
+from .openapi import ReferenceResolver, SwaggerDict
+from .utils import force_real_str, get_consumes, get_produces
+
+if Version(rest_framework.__version__) < Version('3.10'):
+    from rest_framework.schemas.generators import SchemaGenerator
+    from rest_framework.schemas.inspectors import get_pk_description
+else:
+    from rest_framework.schemas import SchemaGenerator
+    from rest_framework.schemas.utils import get_pk_description
+
+
+logger = logging.getLogger(__name__)
 
 PATH_PARAMETER_RE = re.compile(r'{(?P<parameter>\w+)}')
 
 
 class EndpointEnumerator(_EndpointEnumerator):
+    def __init__(self, patterns=None, urlconf=None, request=None):
+        super(EndpointEnumerator, self).__init__(patterns, urlconf)
+        self.request = request
+
     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", 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):
+        if not super(EndpointEnumerator, self).should_include_endpoint(path, callback):
+            return False
+
+        version = getattr(self.request, 'version', None)
+        versioning_class = getattr(callback.cls, 'versioning_class', None)
+        if versioning_class is not None and issubclass(versioning_class, versioning.NamespaceVersioning):
+            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):
+        """If ``request.version`` is not ``None`` and `callback` uses ``URLPathVersioning``, this function replaces
+        the ``version`` parameter in `path` with the actual version.
+
+        :param str path: the templated path
+        :param callback: the view callback
+        :rtype: str
+        """
+        versioning_class = getattr(callback.cls, 'versioning_class', None)
+        if versioning_class is not None and issubclass(versioning_class, versioning.URLPathVersioning):
+            version = getattr(self.request, 'version', None)
+            if version:
+                version_param = getattr(versioning_class, 'version_param', 'version')
+                version_param = '{%s}' % version_param
+                if version_param not in path:
+                    logger.info("view %s uses URLPathVersioning but URL %s has no param %s"
+                                % (callback.cls, path, version_param))
+                path = path.replace(version_param, version)
+
+        return path
+
+    def get_api_endpoints(self, patterns=None, prefix='', app_name=None, namespace=None, ignored_endpoints=None):
+        """
+        Return a list of all available API endpoints by inspecting the URL conf.
+
+        Copied entirely from super.
+        """
+        if patterns is None:
+            patterns = self.patterns
+
+        api_endpoints = []
+        if ignored_endpoints is None:
+            ignored_endpoints = set()
+
+        for pattern in patterns:
+            path_regex = prefix + get_original_route(pattern)
+            if isinstance(pattern, URLPattern):
+                try:
+                    path = self.get_path_from_regex(path_regex)
+                    callback = pattern.callback
+                    url_name = pattern.name
+                    if self.should_include_endpoint(path, callback, app_name or '', namespace or '', url_name):
+                        path = self.replace_version(path, callback)
+
+                        # avoid adding endpoints that have already been seen,
+                        # as Django resolves urls in top-down order
+                        if path in ignored_endpoints:
+                            continue
+                        ignored_endpoints.add(path)
+
+                        for method in self.get_allowed_methods(callback):
+                            endpoint = (path, method, callback)
+                            api_endpoints.append(endpoint)
+                except Exception:  # pragma: no cover
+                    logger.warning('failed to enumerate view', exc_info=True)
+
+            elif isinstance(pattern, URLResolver):
+                nested_endpoints = self.get_api_endpoints(
+                    patterns=pattern.url_patterns,
+                    prefix=path_regex,
+                    app_name="%s:%s" % (app_name, pattern.app_name) if app_name else pattern.app_name,
+                    namespace="%s:%s" % (namespace, pattern.namespace) if namespace else pattern.namespace,
+                    ignored_endpoints=ignored_endpoints
+                )
+                api_endpoints.extend(nested_endpoints)
+            else:
+                logger.warning("unknown pattern type {}".format(type(pattern)))
+
+        api_endpoints = sorted(api_endpoints, key=endpoint_ordering)
+
+        return api_endpoints
+
     def unescape(self, s):
         """Unescape all backslash escapes from `s`.
 
@@ -26,10 +140,10 @@ class EndpointEnumerator(_EndpointEnumerator):
         return re.sub(r'\\(.)', r'\1', s)
 
     def unescape_path(self, path):
-        """Remove backslashes from all path components outside {parameters}. This is needed because
-        Django>=2.0 ``path()``/``RoutePattern`` aggresively escapes all non-parameter path components.
+        """Remove backslashe escapes from all path components outside {parameters}. This is needed because
+        ``simplify_regex`` does not handle this correctly.
 
-        **NOTE:** this might destructively affect some url regex patterns that contain metacharacters (e.g. \w, \d)
+        **NOTE:** this might destructively affect some url regex patterns that contain metacharacters (e.g. \\w, \\d)
         outside path parameter groups; if you are in this category, God help you
 
         :param str path: path possibly containing
@@ -52,16 +166,24 @@ class EndpointEnumerator(_EndpointEnumerator):
 class OpenAPISchemaGenerator(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.
+    Method implementations shamelessly stolen and adapted from rest-framework ``SchemaGenerator``.
     """
     endpoint_enumerator_class = EndpointEnumerator
+    reference_resolver_class = ReferenceResolver
 
-    def __init__(self, info, version, url=None, patterns=None, urlconf=None):
+    def __init__(self, info, version='', url=None, patterns=None, urlconf=None):
         """
 
-        :param .Info info: information about the API
-        :param str version: API version string, takes preedence over the version in `info`
-        :param str url: API
+        :param openapi.Info info: information about the API
+        :param str version: API version string; if omitted, `info.default_version` will be used
+        :param str url: API scheme, host and port; if ``None`` is passed and ``DEFAULT_API_URL`` is not set, the url
+            will be inferred from the request made against the schema view, so you should generally not need to set
+            this parameter explicitly; if the empty string is passed, no host and scheme will be emitted
+
+            If `url` is not ``None`` or the empty string, it must be a scheme-absolute uri (i.e. starting with http://
+            or https://), and any path component is ignored;
+
+            See also: :ref:`documentation on base URL construction <custom-spec-base-url>`
         :param patterns: if given, only these patterns will be enumerated for inclusion in the API spec
         :param urlconf: if patterns is not given, use this urlconf to enumerate patterns;
             if not given, the default urlconf is used
@@ -69,71 +191,145 @@ 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
+
+        if url:
+            parsed_url = urlparse.urlparse(url)
+            if parsed_url.scheme not in ('http', 'https') or not parsed_url.netloc:
+                raise SwaggerGenerationError("`url` must be an absolute HTTP(S) url")
+            if parsed_url.path:
+                logger.warning("path component of api base URL %s is ignored; use FORCE_SCRIPT_NAME instead" % url)
+
+    @property
+    def url(self):
+        return self._gen.url
+
+    def get_security_definitions(self):
+        """Get the security schemes for this API. This determines what is usable in security requirements,
+        and helps clients configure their authorization credentials.
+
+        :return: the security schemes usable with this API
+        :rtype: dict[str,dict] or None
+        """
+        security_definitions = swagger_settings.SECURITY_DEFINITIONS
+        if security_definitions is not None:
+            security_definitions = SwaggerDict._as_odict(security_definitions, {})
+
+        return security_definitions
+
+    def get_security_requirements(self, security_definitions):
+        """Get the base (global) security requirements of the API. This is never called if
+        :meth:`.get_security_definitions` returns `None`.
+
+        :param security_definitions: security definitions as returned by :meth:`.get_security_definitions`
+        :return: the security schemes accepted by default
+        :rtype: list[dict[str,list[str]]] or None
+        """
+        security_requirements = swagger_settings.SECURITY_REQUIREMENTS
+        if security_requirements is None:
+            security_requirements = [{security_scheme: []} for security_scheme in security_definitions]
+
+        security_requirements = [SwaggerDict._as_odict(sr, {}) for sr in security_requirements]
+        security_requirements = sorted(security_requirements, key=list)
+        return security_requirements
 
     def get_schema(self, request=None, public=False):
-        """Generate an :class:`.Swagger` representing the API schema.
+        """Generate a :class:`.Swagger` object representing the API schema.
 
-        :param rest_framework.request.Request request: the request used for filtering
-            accesible endpoints and finding the spec URI
+        :param request: the request used for filtering accessible endpoints and finding the spec URI
+        :type request: rest_framework.request.Request or None
         :param bool public: if True, all endpoints are included regardless of access through `request`
 
         :return: the generated Swagger specification
         :rtype: openapi.Swagger
         """
         endpoints = self.get_endpoints(request)
-        components = ReferenceResolver(openapi.SCHEMA_DEFINITIONS)
-        paths = self.get_paths(endpoints, components, public)
+        components = self.reference_resolver_class(openapi.SCHEMA_DEFINITIONS, force_init=True)
+        self.consumes = get_consumes(api_settings.DEFAULT_PARSER_CLASSES)
+        self.produces = get_produces(api_settings.DEFAULT_RENDERER_CLASSES)
+        paths, prefix = self.get_paths(endpoints, components, request, public)
 
-        url = self._gen.url
-        if not url and request is not None:
+        security_definitions = self.get_security_definitions()
+        if security_definitions:
+            security_requirements = self.get_security_requirements(security_definitions)
+        else:
+            security_requirements = None
+
+        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,
-            _url=url, _version=self.version, **dict(components)
+            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)
         )
 
     def create_view(self, callback, method, request=None):
         """Create a view instance from a view callback as registered in urlpatterns.
 
-        :param callable callback: view callback registered in urlpatterns
+        :param callback: view callback registered in urlpatterns
         :param str method: HTTP method
-        :param rest_framework.request.Request request: request to bind to the view
+        :param request: request to bind to the view
+        :type request: rest_framework.request.Request or None
         :return: the view instance
         """
         view = self._gen.create_view(callback, method, request)
-        overrides = getattr(callback, 'swagger_auto_schema', None)
+        overrides = getattr(callback, '_swagger_auto_schema', None)
         if overrides is not None:
             # decorated function based view must have its decorator information passed on to the re-instantiated view
             for method, _ in overrides.items():
                 view_method = getattr(view, method, None)
                 if view_method is not None:  # pragma: no cover
-                    setattr(view_method.__func__, 'swagger_auto_schema', overrides)
+                    setattr(view_method.__func__, '_swagger_auto_schema', overrides)
+
+        setattr(view, 'swagger_fake_view', True)
         return view
 
-    def get_endpoints(self, request=None):
+    def coerce_path(self, path, view):
+        """Coerce {pk} path arguments into the name of the model field, where possible. This is cleaner for an
+        external representation (i.e. "this is an identifier", not "this is a database primary key").
+
+        :param str path: the path
+        :param rest_framework.views.APIView view: associated view
+        :rtype: str
+        """
+        if '{pk}' not in path:
+            return path
+
+        model = getattr(get_queryset_from_view(view), 'model', None)
+        if model:
+            field_name = get_pk_name(model)
+        else:
+            field_name = 'id'
+        return path.replace('{pk}', '{%s}' % field_name)
+
+    def get_endpoints(self, request):
         """Iterate over all the registered endpoints in the API and return a fake view with the right parameters.
 
-        :param rest_framework.request.Request request: request to bind to the endpoint views
+        :param request: request to bind to the endpoint views
+        :type request: rest_framework.request.Request or None
         :return: {path: (view_class, list[(http_method, view_instance)])
-        :rtype: dict
+        :rtype: dict[str,(type,list[(str,rest_framework.views.APIView)])]
         """
-        enumerator = self.endpoint_enumerator_class(self._gen.patterns, self._gen.urlconf)
+        enumerator = self.endpoint_enumerator_class(self._gen.patterns, self._gen.urlconf, request=request)
         endpoints = enumerator.get_api_endpoints()
 
         view_paths = defaultdict(list)
         view_cls = {}
         for path, method, callback in endpoints:
             view = self.create_view(callback, method, request)
-            path = self._gen.coerce_path(path, method, view)
+            path = self.coerce_path(path, view)
             view_paths[path].append((method, view))
             view_cls[path] = callback.cls
         return {path: (view_cls[path], methods) for path, methods in view_paths.items()}
 
     def get_operation_keys(self, subpath, method, view):
-        """Return a list of keys that should be used to group an operation within the specification.
-
-        ::
+        """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")
@@ -145,42 +341,137 @@ class OpenAPISchemaGenerator(object):
         :param str subpath: path to the operation with any common prefix/base path removed
         :param str method: HTTP method
         :param view: the view associated with the operation
-        :rtype: tuple
+        :rtype: list[str]
         """
         return self._gen.get_keys(subpath, method, view)
 
-    def get_paths(self, endpoints, components, public):
+    def determine_path_prefix(self, paths):
+        """
+        Given a list of all paths, return the common prefix which should be
+        discounted when generating a schema structure.
+
+        This will be the longest common string that does not include that last
+        component of the URL, or the last component before a path parameter.
+
+        For example: ::
+
+            /api/v1/users/
+            /api/v1/users/{pk}/
+
+        The path prefix is ``/api/v1/``.
+
+        :param list[str] paths: list of paths
+        :rtype: str
+        """
+        return self._gen.determine_path_prefix(paths)
+
+    def should_include_endpoint(self, path, method, view, public):
+        """Check if a given endpoint should be included in the resulting schema.
+
+        :param str path: request path
+        :param str method: http request method
+        :param view: instantiated view callback
+        :param bool public: if True, all endpoints are included regardless of access through `request`
+        :returns: true if the view should be excluded
+        :rtype: bool
+        """
+        return public or self._gen.has_view_permissions(path, method, view)
+
+    def get_paths_object(self, paths):
+        """Construct the Swagger Paths object.
+
+        :param OrderedDict[str,openapi.PathItem] paths: mapping of paths to :class:`.PathItem` objects
+        :returns: the :class:`.Paths` object
+        :rtype: openapi.Paths
+        """
+        return openapi.Paths(paths=paths)
+
+    def get_paths(self, endpoints, components, request, public):
         """Generate the Swagger Paths for the API from the given endpoints.
 
         :param dict endpoints: endpoints as returned by get_endpoints
         :param ReferenceResolver components: resolver/container for Swagger References
+        :param Request request: the request made against the schema view; can be None
         :param bool public: if True, all endpoints are included regardless of access through `request`
-        :rtype: openapi.Paths
+        :returns: the :class:`.Paths` object and the longest common path prefix, as a 2-tuple
+        :rtype: tuple[openapi.Paths,str]
         """
         if not endpoints:
-            return openapi.Paths(paths={})
+            return openapi.Paths(paths={}), ''
+
+        prefix = self.determine_path_prefix(list(endpoints.keys())) or ''
+        assert '{' not in prefix, "base path cannot be templated in swagger 2.0"
 
-        prefix = self._gen.determine_path_prefix(endpoints.keys())
         paths = OrderedDict()
-
-        default_schema_cls = SwaggerAutoSchema
         for path, (view_cls, methods) in sorted(endpoints.items()):
-            path_parameters = self.get_path_parameters(path, view_cls)
             operations = {}
             for method, view in methods:
-                if not public and not self._gen.has_view_permissions(path, method, view):
+                if not self.should_include_endpoint(path, method, view, public):
                     continue
 
-                operation_keys = self.get_operation_keys(path[len(prefix):], method, view)
-                overrides = self.get_overrides(view, method)
-                auto_schema_cls = overrides.get('auto_schema', default_schema_cls)
-                schema = auto_schema_cls(view, path, method, overrides, components)
-                operations[method.lower()] = schema.get_operation(operation_keys)
+                operation = self.get_operation(view, path, prefix, method, components, request)
+                if operation is not None:
+                    operations[method.lower()] = operation
 
             if operations:
-                paths[path] = openapi.PathItem(parameters=path_parameters, **operations)
+                # since the common prefix is used as the API basePath, it must be stripped
+                # from individual paths when writing them into the swagger document
+                path_suffix = path[len(prefix):]
+                if not path_suffix.startswith('/'):
+                    path_suffix = '/' + path_suffix
+                paths[path_suffix] = self.get_path_item(path, view_cls, operations)
 
-        return openapi.Paths(paths=paths)
+        return self.get_paths_object(paths), prefix
+
+    def get_operation(self, view, path, prefix, method, components, request):
+        """Get an :class:`.Operation` for the given API endpoint (path, method). This method delegates to
+        :meth:`~.inspectors.ViewInspector.get_operation` of a :class:`~.inspectors.ViewInspector` determined
+        according to settings and :func:`@swagger_auto_schema <.swagger_auto_schema>` overrides.
+
+        :param view: the view associated with this endpoint
+        :param str path: the path component of the operation URL
+        :param str prefix: common path prefix among all endpoints
+        :param str method: the http method of the operation
+        :param openapi.ReferenceResolver components: referenceable components
+        :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)
+
+        # the inspector class can be specified, in decreasing order of priorty,
+        #   1. globaly via DEFAULT_AUTO_SCHEMA_CLASS
+        view_inspector_cls = swagger_settings.DEFAULT_AUTO_SCHEMA_CLASS
+        #   2. on the view/viewset class
+        view_inspector_cls = getattr(view, 'swagger_schema', view_inspector_cls)
+        #   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, operation_keys)
+        operation = view_inspector.get_operation(operation_keys)
+        if operation is None:
+            return None
+
+        if 'consumes' in operation and set(operation.consumes) == set(self.consumes):
+            del operation.consumes
+        if 'produces' in operation and 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
+        API.
+
+        :param str path: the path
+        :param type view_cls: the view that was bound to this path in urlpatterns
+        :param dict[str,openapi.Operation] operations: operations defined on this path, keyed by lowercase HTTP method
+        :rtype: openapi.PathItem
+        """
+        path_parameters = self.get_path_parameters(path, view_cls)
+        return openapi.PathItem(parameters=path_parameters, **operations)
 
     def get_overrides(self, view, method):
         """Get overrides specified for a given operation.
@@ -193,11 +484,11 @@ class OpenAPISchemaGenerator(object):
         method = method.lower()
         action = getattr(view, 'action', method)
         action_method = getattr(view, action, None)
-        overrides = getattr(action_method, 'swagger_auto_schema', {})
+        overrides = getattr(action_method, '_swagger_auto_schema', {})
         if method in overrides:
             overrides = overrides[method]
 
-        return overrides
+        return copy.deepcopy(overrides)
 
     def get_path_parameters(self, path, view_cls):
         """Return a list of Parameter instances corresponding to any templated path variables.
@@ -208,17 +499,24 @@ class OpenAPISchemaGenerator(object):
         :rtype: list[openapi.Parameter]
         """
         parameters = []
-        queryset = getattr(view_cls, 'queryset', None)
-        model = getattr(getattr(view_cls, 'queryset', None), 'model', None)
+        queryset = get_queryset_from_view(view_cls)
 
-        for variable in uritemplate.variables(path):
-            model, model_field = get_model_field(queryset, variable)
-            attrs = inspect_model_field(model, model_field)
-            if hasattr(view_cls, 'lookup_value_regex') and getattr(view_cls, 'lookup_field', None) == variable:
-                attrs['pattern'] = view_cls.lookup_value_regex
+        for variable in sorted(uritemplate.variables(path)):
+            model, model_field = get_queryset_field(queryset, variable)
+            attrs = get_basic_type_info(model_field) or {'type': openapi.TYPE_STRING}
+            if getattr(view_cls, 'lookup_field', None) == variable and attrs['type'] == openapi.TYPE_STRING:
+                attrs['pattern'] = getattr(view_cls, 'lookup_value_regex', attrs.get('pattern', None))
+
+            if model_field and getattr(model_field, 'help_text', False):
+                description = model_field.help_text
+            elif model_field and getattr(model_field, 'primary_key', False):
+                description = get_pk_description(model, model_field)
+            else:
+                description = None
 
             field = openapi.Parameter(
                 name=variable,
+                description=force_real_str(description),
                 required=True,
                 in_=openapi.IN_PATH,
                 **attrs

src/drf_yasg/inspectors.py

@@ -1,485 +0,0 @@
-import inspect
-from collections import OrderedDict
-
-import coreschema
-from rest_framework import serializers, status
-from rest_framework.request import is_form_media_type
-from rest_framework.schemas import AutoSchema
-from rest_framework.status import is_success
-from rest_framework.viewsets import GenericViewSet
-
-from . import openapi
-from .errors import SwaggerGenerationError
-from .utils import serializer_field_to_swagger, no_body, is_list_view, param_list_to_odict
-
-
-def force_serializer_instance(serializer):
-    """Force `serializer` into a ``Serializer`` instance. If it is not a ``Serializer`` class or instance, raises
-    an assertion error.
-
-    :param serializer: serializer class or instance
-    :return: serializer instance
-    """
-    if inspect.isclass(serializer):
-        assert issubclass(serializer, serializers.BaseSerializer), "Serializer required, not %s" % serializer.__name__
-        return serializer()
-
-    assert isinstance(serializer, serializers.BaseSerializer), \
-        "Serializer class or instance required, not %s" % type(serializer).__name__
-    return serializer
-
-
-class SwaggerAutoSchema(object):
-    body_methods = ('PUT', 'PATCH', 'POST')  #: methods allowed to have a request body
-
-    def __init__(self, view, path, method, overrides, components):
-        """Inspector class responsible for providing :class:`.Operation` definitions given a
-
-        :param view: the view associated with this endpoint
-        :param str path: the path component of the operation URL
-        :param str method: the http method of the operation
-        :param dict overrides: manual overrides as passed to :func:`@swagger_auto_schema <.swagger_auto_schema>`
-        :param openapi.ReferenceResolver components: referenceable components
-        """
-        super(SwaggerAutoSchema, self).__init__()
-        self._sch = AutoSchema()
-        self.view = view
-        self.path = path
-        self.method = method
-        self.overrides = overrides
-        self.components = components
-        self._sch.view = view
-
-    def get_operation(self, operation_keys):
-        """Get an :class:`.Operation` for the given API endpoint (path, method).
-        This includes query, body parameters and response schemas.
-
-        :param tuple[str] operation_keys: an array of keys describing the hierarchical layout of this view in the API;
-          e.g. ``('snippets', 'list')``, ``('snippets', 'retrieve')``, etc.
-        :rtype: openapi.Operation
-        """
-        consumes = self.get_consumes()
-
-        body = self.get_request_body_parameters(consumes)
-        query = self.get_query_parameters()
-        parameters = body + query
-        parameters = [param for param in parameters if param is not None]
-        parameters = self.add_manual_parameters(parameters)
-
-        description = self.get_description()
-
-        responses = self.get_responses()
-
-        return openapi.Operation(
-            operation_id='_'.join(operation_keys),
-            description=description,
-            responses=responses,
-            parameters=parameters,
-            consumes=consumes,
-            tags=[operation_keys[0]],
-        )
-
-    def get_request_body_parameters(self, consumes):
-        """Return the request body parameters for this view. |br|
-        This is either:
-
-        -  a list with a single object Parameter with a :class:`.Schema` derived from the request serializer
-        -  a list of primitive Parameters parsed as form data
-
-        :param list[str] consumes: a list of accepted MIME types as returned by :meth:`.get_consumes`
-        :return: a (potentially empty) list of :class:`.Parameter`\ s either ``in: body`` or ``in: formData``
-        :rtype: list[openapi.Parameter]
-        """
-        serializer = self.get_request_serializer()
-        schema = None
-        if serializer is None:
-            return []
-
-        if isinstance(serializer, openapi.Schema.OR_REF):
-            schema = serializer
-
-        if any(is_form_media_type(encoding) for encoding in consumes):
-            if schema is not None:
-                raise SwaggerGenerationError("form request body cannot be a Schema")
-            return self.get_request_form_parameters(serializer)
-        else:
-            if schema is None:
-                schema = self.get_request_body_schema(serializer)
-            return [self.make_body_parameter(schema)]
-
-    def get_view_serializer(self):
-        """Return the serializer as defined by the view's ``get_serializer()`` method.
-
-        :return: the view's ``Serializer``
-        """
-        if not hasattr(self.view, 'get_serializer'):
-            return None
-        return self.view.get_serializer()
-
-    def get_request_serializer(self):
-        """Return the request serializer (used for parsing the request payload) for this endpoint.
-
-        :return: the request serializer, or one of :class:`.Schema`, :class:`.SchemaRef`, ``None``
-        """
-        body_override = self.overrides.get('request_body', None)
-
-        if body_override is not None:
-            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?")
-            if isinstance(body_override, openapi.Schema.OR_REF):
-                return body_override
-            return force_serializer_instance(body_override)
-        elif self.method in self.body_methods:
-            return self.get_view_serializer()
-
-        return None
-
-    def get_request_form_parameters(self, serializer):
-        """Given a Serializer, return a list of ``in: formData`` :class:`.Parameter`\ s.
-
-        :param serializer: the view's request serializer as returned by :meth:`.get_request_serializer`
-        :rtype: list[openapi.Parameter]
-        """
-        return self.serializer_to_parameters(serializer, in_=openapi.IN_FORM)
-
-    def get_request_body_schema(self, serializer):
-        """Return the :class:`.Schema` for a given request's body data. Only applies to PUT, PATCH and POST requests.
-
-        :param serializer: the view's request serializer as returned by :meth:`.get_request_serializer`
-        :rtype: openapi.Schema
-        """
-        return self.serializer_to_schema(serializer)
-
-    def make_body_parameter(self, schema):
-        """Given a :class:`.Schema` object, create an ``in: body`` :class:`.Parameter`.
-
-        :param openapi.Schema schema: the request body schema
-        :rtype: openapi.Parameter
-        """
-        return openapi.Parameter(name='data', in_=openapi.IN_BODY, required=True, schema=schema)
-
-    def add_manual_parameters(self, parameters):
-        """Add/replace parameters from the given list of automatically generated request parameters.
-
-        :param list[openapi.Parameter] parameters: genereated parameters
-        :return: modified parameters
-        :rtype: list[openapi.Parameter]
-        """
-        parameters = param_list_to_odict(parameters)
-        manual_parameters = self.overrides.get('manual_parameters', None) or []
-
-        if any(param.in_ == openapi.IN_BODY for param in manual_parameters):  # pragma: no cover
-            raise SwaggerGenerationError("specify the body parameter as a Schema or Serializer in request_body")
-        if any(param.in_ == openapi.IN_FORM for param in manual_parameters):  # pragma: no cover
-            if any(param.in_ == openapi.IN_BODY for param in parameters.values()):
-                raise SwaggerGenerationError("cannot add form parameters when the request has a request schema; "
-                                             "did you forget to set an appropriate parser class on the view?")
-
-        parameters.update(param_list_to_odict(manual_parameters))
-        return list(parameters.values())
-
-    def get_responses(self):
-        """Get the possible responses for this view as a swagger :class:`.Responses` object.
-
-        :return: the documented responses
-        :rtype: openapi.Responses
-        """
-        response_serializers = self.get_response_serializers()
-        return openapi.Responses(
-            responses=self.get_response_schemas(response_serializers)
-        )
-
-    def get_paged_response_schema(self, response_schema):
-        """Add appropriate paging fields to a response :class:`.Schema`.
-
-        :param openapi.Schema response_schema: the response schema that must be paged.
-        :rtype: openapi.Schema
-        """
-        assert response_schema.type == openapi.TYPE_ARRAY, "array return expected for paged response"
-        paged_schema = openapi.Schema(
-            type=openapi.TYPE_OBJECT,
-            properties={
-                'count': openapi.Schema(type=openapi.TYPE_INTEGER),
-                'next': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI),
-                'previous': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI),
-                'results': response_schema,
-            },
-            required=['count', 'results']
-        )
-
-        return paged_schema
-
-    def get_default_responses(self):
-        """Get the default responses determined for this view from the request serializer and request method.
-
-        :type: dict[str, openapi.Schema]
-        """
-        method = self.method.lower()
-
-        default_status = status.HTTP_200_OK
-        default_schema = ''
-        if method == 'post':
-            default_status = status.HTTP_201_CREATED
-            default_schema = self.get_request_serializer() or self.get_view_serializer()
-        elif method == 'delete':
-            default_status = status.HTTP_204_NO_CONTENT
-        elif method in ('get', 'put', 'patch'):
-            default_schema = self.get_request_serializer() or self.get_view_serializer()
-
-        default_schema = default_schema or ''
-        if any(is_form_media_type(encoding) for encoding in self.get_consumes()):
-            default_schema = ''
-        if default_schema:
-            if not isinstance(default_schema, openapi.Schema):
-                default_schema = self.serializer_to_schema(default_schema)
-            if is_list_view(self.path, self.method, self.view) and self.method.lower() == 'get':
-                default_schema = openapi.Schema(type=openapi.TYPE_ARRAY, items=default_schema)
-            if self.should_page():
-                default_schema = self.get_paged_response_schema(default_schema)
-
-        return {str(default_status): default_schema}
-
-    def get_response_serializers(self):
-        """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, :class:`.Schema`, :class:`.SchemaRef` or :class:`.Response` objects. See
-        :func:`@swagger_auto_schema <.swagger_auto_schema>` for more details.
-
-        :return: the response serializers
-        :rtype: dict
-        """
-        manual_responses = self.overrides.get('responses', None) or {}
-        manual_responses = OrderedDict((str(sc), resp) for sc, resp in manual_responses.items())
-
-        responses = {}
-        if not any(is_success(int(sc)) for sc in manual_responses if sc != 'default'):
-            responses = self.get_default_responses()
-
-        responses.update((str(sc), resp) for sc, resp in manual_responses.items())
-        return responses
-
-    def get_response_schemas(self, response_serializers):
-        """Return the :class:`.openapi.Response` objects calculated for this view.
-
-        :param dict response_serializers: response serializers as returned by :meth:`.get_response_serializers`
-        :return: a dictionary of status code to :class:`.Response` object
-        :rtype: dict[str, openapi.Response]
-        """
-        responses = {}
-        for sc, serializer in response_serializers.items():
-            if isinstance(serializer, str):
-                response = openapi.Response(
-                    description=serializer
-                )
-            elif isinstance(serializer, openapi.Response):
-                response = serializer
-                if not isinstance(response.schema, openapi.Schema.OR_REF):
-                    serializer = force_serializer_instance(response.schema)
-                    response.schema = self.serializer_to_schema(serializer)
-            elif isinstance(serializer, openapi.Schema.OR_REF):
-                response = openapi.Response(
-                    description='',
-                    schema=serializer,
-                )
-            else:
-                serializer = force_serializer_instance(serializer)
-                response = openapi.Response(
-                    description='',
-                    schema=self.serializer_to_schema(serializer),
-                )
-
-            responses[str(sc)] = response
-
-        return responses
-
-    def get_query_serializer(self):
-        """Return the query serializer (used for parsing query parameters) for this endpoint.
-
-        :return: the query serializer, or ``None``
-        """
-        query_serializer = self.overrides.get('query_serializer', None)
-        if query_serializer is not None:
-            query_serializer = force_serializer_instance(query_serializer)
-        return query_serializer
-
-    def get_query_parameters(self):
-        """Return the query parameters accepted by this view.
-
-        :rtype: list[openapi.Parameter]
-        """
-        natural_parameters = self.get_filter_parameters() + self.get_pagination_parameters()
-
-        query_serializer = self.get_query_serializer()
-        serializer_parameters = []
-        if query_serializer is not None:
-            serializer_parameters = self.serializer_to_parameters(query_serializer, in_=openapi.IN_QUERY)
-
-            if len(set(param_list_to_odict(natural_parameters)) & set(param_list_to_odict(serializer_parameters))) != 0:
-                raise SwaggerGenerationError(
-                    "your query_serializer contains fields that conflict with the "
-                    "filter_backend or paginator_class on the view - %s %s" % (self.method, self.path)
-                )
-
-        return natural_parameters + serializer_parameters
-
-    def should_filter(self):
-        """Determine whether filter backend parameters should be included for this request.
-
-        :rtype: bool
-        """
-        if not getattr(self.view, 'filter_backends', None):
-            return False
-
-        if self.method.lower() not in ["get", "delete"]:
-            return False
-
-        if not isinstance(self.view, GenericViewSet):
-            return True
-
-        return is_list_view(self.path, self.method, self.view)
-
-    def get_filter_backend_parameters(self, filter_backend):
-        """Get the filter parameters for a single filter backend **instance**.
-
-        :param BaseFilterBackend filter_backend: the filter backend
-        :rtype: list[openapi.Parameter]
-        """
-        fields = []
-        if hasattr(filter_backend, 'get_schema_fields'):
-            fields = filter_backend.get_schema_fields(self.view)
-        return [self.coreapi_field_to_parameter(field) for field in fields]
-
-    def get_filter_parameters(self):
-        """Return the parameters added to the view by its filter backends.
-
-        :rtype: list[openapi.Parameter]
-        """
-        if not self.should_filter():
-            return []
-
-        fields = []
-        for filter_backend in self.view.filter_backends:
-            fields += self.get_filter_backend_parameters(filter_backend())
-
-        return fields
-
-    def should_page(self):
-        """Determine whether paging parameters and structure should be added to this operation's request and response.
-
-        :rtype: bool
-        """
-        if not hasattr(self.view, 'paginator'):
-            return False
-
-        if self.view.paginator is None:
-            return False
-
-        if self.method.lower() != 'get':
-            return False
-
-        return is_list_view(self.path, self.method, self.view)
-
-    def get_paginator_parameters(self, paginator):
-        """Get the pagination parameters for a single paginator **instance**.
-
-        :param BasePagination paginator: the paginator
-        :rtype: list[openapi.Parameter]
-        """
-        fields = []
-        if hasattr(paginator, 'get_schema_fields'):
-            fields = paginator.get_schema_fields(self.view)
-
-        return [self.coreapi_field_to_parameter(field) for field in fields]
-
-    def get_pagination_parameters(self):
-        """Return the parameters added to the view by its paginator.
-
-        :rtype: list[openapi.Parameter]
-        """
-        if not self.should_page():
-            return []
-
-        return self.get_paginator_parameters(self.view.paginator)
-
-    def get_description(self):
-        """Return an operation description determined as appropriate from the view's method and class docstrings.
-
-        :return: the operation description
-        :rtype: str
-        """
-        description = self.overrides.get('operation_description', None)
-        if description is None:
-            description = self._sch.get_description(self.path, self.method)
-        return description
-
-    def get_consumes(self):
-        """Return the MIME types this endpoint can consume.
-
-        :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]
-
-    def serializer_to_schema(self, serializer):
-        """Convert a DRF Serializer instance to an :class:`.openapi.Schema`.
-
-        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
-        :rtype: openapi.Schema
-        """
-        definitions = self.components.with_scope(openapi.SCHEMA_DEFINITIONS)
-        return serializer_field_to_swagger(serializer, openapi.Schema, definitions)
-
-    def serializer_to_parameters(self, serializer, in_):
-        """Convert a DRF serializer into a list of :class:`.Parameter`\ s using :meth:`.field_to_parameter`
-
-        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
-        :param str in_: the location of the parameters, one of the `openapi.IN_*` constants
-        :rtype: list[openapi.Parameter]
-        """
-        fields = getattr(serializer, 'fields', {})
-        return [
-            self.field_to_parameter(value, key, in_)
-            for key, value
-            in fields.items()
-        ]
-
-    def field_to_parameter(self, field, name, in_):
-        """Convert a DRF serializer Field to a swagger :class:`.Parameter` object.
-
-        :param coreapi.Field field:
-        :param str name: the name of the parameter
-        :param str in_: the location of the parameter, one of the `openapi.IN_*` constants
-        :rtype: openapi.Parameter
-        """
-        return serializer_field_to_swagger(field, openapi.Parameter, name=name, in_=in_)
-
-    def coreapi_field_to_parameter(self, field):
-        """Convert an instance of `coreapi.Field` to a swagger :class:`.Parameter` object.
-
-        :param coreapi.Field field:
-        :rtype: openapi.Parameter
-        """
-        location_to_in = {
-            'query': openapi.IN_QUERY,
-            'path': openapi.IN_PATH,
-            'form': openapi.IN_FORM,
-            'body': openapi.IN_FORM,
-        }
-        coreapi_types = {
-            coreschema.Integer: openapi.TYPE_INTEGER,
-            coreschema.Number: openapi.TYPE_NUMBER,
-            coreschema.String: openapi.TYPE_STRING,
-            coreschema.Boolean: openapi.TYPE_BOOLEAN,
-        }
-        return openapi.Parameter(
-            name=field.name,
-            in_=location_to_in[field.location],
-            type=coreapi_types.get(type(field.schema), openapi.TYPE_STRING),
-            required=field.required,
-            description=field.schema.description,
-        )

src/drf_yasg/inspectors/__init__.py

@@ -0,0 +1,35 @@
+from ..app_settings import swagger_settings
+from .base import (
+    BaseInspector, FieldInspector, FilterInspector, NotHandled, PaginatorInspector, SerializerInspector, ViewInspector
+)
+from .field import (
+    CamelCaseJSONFilter, ChoiceFieldInspector, DictFieldInspector, FileFieldInspector, HiddenFieldInspector,
+    InlineSerializerInspector, JSONFieldInspector, RecursiveFieldInspector, ReferencingSerializerInspector,
+    RelatedFieldInspector, SerializerMethodFieldInspector, SimpleFieldInspector, StringDefaultFieldInspector
+)
+from .query import CoreAPICompatInspector, DjangoRestResponsePagination
+from .view import SwaggerAutoSchema
+
+# these settings must be accessed only after defining/importing all the classes in this module to avoid ImportErrors
+ViewInspector.field_inspectors = swagger_settings.DEFAULT_FIELD_INSPECTORS
+ViewInspector.filter_inspectors = swagger_settings.DEFAULT_FILTER_INSPECTORS
+ViewInspector.paginator_inspectors = swagger_settings.DEFAULT_PAGINATOR_INSPECTORS
+
+__all__ = [
+    # base inspectors
+    'BaseInspector', 'FilterInspector', 'PaginatorInspector', 'FieldInspector', 'SerializerInspector', 'ViewInspector',
+
+    # filter and pagination inspectors
+    'CoreAPICompatInspector', 'DjangoRestResponsePagination',
+
+    # field inspectors
+    'InlineSerializerInspector', 'RecursiveFieldInspector', 'ReferencingSerializerInspector', 'RelatedFieldInspector',
+    'SimpleFieldInspector', 'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector', 'JSONFieldInspector',
+    'StringDefaultFieldInspector', 'CamelCaseJSONFilter', 'HiddenFieldInspector', 'SerializerMethodFieldInspector',
+
+    # view inspectors
+    'SwaggerAutoSchema',
+
+    # module constants
+    'NotHandled',
+]

src/drf_yasg/inspectors/base.py

@@ -0,0 +1,469 @@
+import inspect
+import logging
+
+from rest_framework import serializers
+
+from .. import openapi
+from ..utils import force_real_str, get_field_default, get_object_classes, is_list_view
+
+#: Sentinel value that inspectors must return to signal that they do not know how to handle an object
+NotHandled = object()
+
+logger = logging.getLogger(__name__)
+
+
+def is_callable_method(cls_or_instance, method_name):
+    method = getattr(cls_or_instance, method_name)
+    if inspect.ismethod(method) and getattr(method, '__self__', None):
+        # bound classmethod or instance method
+        return method, True
+
+    try:
+        # inspect.getattr_static was added in python 3.2
+        from inspect import getattr_static
+
+        # on python 3, both unbound instance methods (i.e. getattr(cls, mth)) and static methods are plain functions
+        # getattr_static allows us to check the type of the method descriptor; for `@staticmethod` this is staticmethod
+        return method, isinstance(getattr_static(cls_or_instance, method_name, None), staticmethod)
+    except ImportError:
+        # python 2 still has unbound methods, so ismethod <=> !staticmethod TODO: remove when dropping python 2.7
+        return method, not inspect.ismethod(method)
+
+
+def call_view_method(view, method_name, fallback_attr=None, default=None):
+    """Call a view method which might throw an exception. If an exception is thrown, log an informative error message
+    and return the value of fallback_attr, or default if not present. The method must be callable without any arguments
+    except cls or self.
+
+    :param view: view class or instance; if a class is passed, instance methods won't be called
+    :type view: rest_framework.views.APIView or type[rest_framework.views.APIView]
+    :param str method_name: name of a method on the view
+    :param str fallback_attr: name of an attribute on the view to fall back on, if calling the method fails
+    :param default: default value if all else fails
+    :return: view method's return value, or value of view's fallback_attr, or default
+    :rtype: any or None
+    """
+    if hasattr(view, method_name):
+        try:
+            view_method, is_callabale = is_callable_method(view, method_name)
+            if is_callabale:
+                return view_method()
+        except Exception:  # pragma: no cover
+            logger.warning("view's %s raised exception during schema generation; use "
+                           "`getattr(self, 'swagger_fake_view', False)` to detect and short-circuit this",
+                           type(view).__name__, exc_info=True)
+
+    if fallback_attr and hasattr(view, fallback_attr):
+        return getattr(view, fallback_attr)
+
+    return default
+
+
+class BaseInspector(object):
+    def __init__(self, view, path, method, components, request):
+        """
+        :param rest_framework.views.APIView view: the view associated with this endpoint
+        :param str path: the path component of the operation URL
+        :param str method: the http method of the operation
+        :param openapi.ReferenceResolver components: referenceable components
+        :param rest_framework.request.Request request: the request made against the schema view; can be None
+        """
+        self.view = view
+        self.path = path
+        self.method = method
+        self.components = components
+        self.request = request
+
+    def process_result(self, result, method_name, obj, **kwargs):
+        """After an inspector handles an object (i.e. returns a value other than :data:`.NotHandled`), all inspectors
+        that were probed get the chance to alter the result, in reverse order. The inspector that handled the object
+        is the first to receive a ``process_result`` call with the object it just returned.
+
+        This behaviour is similar to the Django request/response middleware processing.
+
+        If this inspector has no post-processing to do, it should just ``return result`` (the default implementation).
+
+        :param result: the return value of the winning inspector, or ``None`` if no inspector handled the object
+        :param str method_name: name of the method that was called on the inspector
+        :param obj: first argument passed to inspector method
+        :param kwargs: additional arguments passed to inspector method
+        :return:
+        """
+        return result
+
+    def probe_inspectors(self, inspectors, method_name, obj, initkwargs=None, **kwargs):
+        """Probe a list of inspectors with a given object. The first inspector in the list to return a value that
+        is not :data:`.NotHandled` wins.
+
+        :param list[type[BaseInspector]] inspectors: list of inspectors to probe
+        :param str method_name: name of the target method on the inspector
+        :param obj: first argument to inspector method
+        :param dict initkwargs: extra kwargs for instantiating inspector class
+        :param kwargs: additional arguments to inspector method
+        :return: the return value of the winning inspector, or ``None`` if no inspector handled the object
+        """
+        initkwargs = initkwargs or {}
+        tried_inspectors = []
+
+        for inspector in inspectors:
+            assert inspect.isclass(inspector), "inspector must be a class, not an object"
+            assert issubclass(inspector, BaseInspector), "inspectors must subclass BaseInspector"
+
+            inspector = inspector(self.view, self.path, self.method, self.components, self.request, **initkwargs)
+            tried_inspectors.append(inspector)
+            method = getattr(inspector, method_name, None)
+            if method is None:
+                continue
+
+            result = method(obj, **kwargs)
+            if result is not NotHandled:
+                break
+        else:  # pragma: no cover
+            logger.warning("%s ignored because no inspector in %s handled it (operation: %s)",
+                           obj, inspectors, method_name)
+            result = None
+
+        for inspector in reversed(tried_inspectors):
+            result = inspector.process_result(result, method_name, obj, **kwargs)
+
+        return result
+
+    def get_renderer_classes(self):
+        """Get the renderer classes of this view by calling `get_renderers`.
+
+        :return: renderer classes
+        :rtype: list[type[rest_framework.renderers.BaseRenderer]]
+        """
+        return get_object_classes(call_view_method(self.view, 'get_renderers', 'renderer_classes', []))
+
+    def get_parser_classes(self):
+        """Get the parser classes of this view by calling `get_parsers`.
+
+        :return: parser classes
+        :rtype: list[type[rest_framework.parsers.BaseParser]]
+        """
+        return get_object_classes(call_view_method(self.view, 'get_parsers', 'parser_classes', []))
+
+
+class PaginatorInspector(BaseInspector):
+    """Base inspector for paginators.
+
+    Responisble for determining extra query parameters and response structure added by given paginators.
+    """
+
+    def get_paginator_parameters(self, paginator):
+        """Get the pagination parameters for a single paginator **instance**.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `paginator`.
+
+        :param BasePagination paginator: the paginator
+        :rtype: list[openapi.Parameter]
+        """
+        return NotHandled
+
+    def get_paginated_response(self, paginator, response_schema):
+        """Add appropriate paging fields to a response :class:`.Schema`.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `paginator`.
+
+        :param BasePagination paginator: the paginator
+        :param openapi.Schema response_schema: the response schema that must be paged.
+        :rtype: openapi.Schema
+        """
+        return NotHandled
+
+
+class FilterInspector(BaseInspector):
+    """Base inspector for filter backends.
+
+    Responsible for determining extra query parameters added by given filter backends.
+    """
+
+    def get_filter_parameters(self, filter_backend):
+        """Get the filter parameters for a single filter backend **instance**.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `filter_backend`.
+
+        :param BaseFilterBackend filter_backend: the filter backend
+        :rtype: list[openapi.Parameter]
+        """
+        return NotHandled
+
+
+class FieldInspector(BaseInspector):
+    """Base inspector for serializers and serializer fields. """
+
+    def __init__(self, view, path, method, components, request, field_inspectors):
+        super(FieldInspector, self).__init__(view, path, method, components, request)
+        self.field_inspectors = field_inspectors
+
+    def add_manual_fields(self, serializer_or_field, schema):
+        """Set fields from the ``swagger_schem_fields`` attribute on the Meta class. This method is called
+        only for serializers or fields that are converted into ``openapi.Schema`` objects.
+
+        :param serializer_or_field: serializer or field instance
+        :param openapi.Schema schema: the schema object to be modified in-place
+        """
+        meta = getattr(serializer_or_field, 'Meta', None)
+        swagger_schema_fields = getattr(meta, 'swagger_schema_fields', {})
+        if swagger_schema_fields:
+            for attr, val in swagger_schema_fields.items():
+                setattr(schema, attr, val)
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        """Convert a drf Serializer or Field instance into a Swagger object.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `field`.
+
+        :param rest_framework.serializers.Field field: the source field
+        :param type[openapi.SwaggerDict] swagger_object_type: should be one of Schema, Parameter, Items
+        :param bool use_references: if False, forces all objects to be declared inline
+           instead of by referencing other components
+        :param kwargs: extra attributes for constructing the object;
+           if swagger_object_type is Parameter, ``name`` and ``in_`` should be provided
+        :return: the swagger object
+        :rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef
+        """
+        return NotHandled
+
+    def probe_field_inspectors(self, field, swagger_object_type, use_references, **kwargs):
+        """Helper method for recursively probing `field_inspectors` to handle a given field.
+
+        All arguments are the same as :meth:`.field_to_swagger_object`.
+
+        :rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef
+        """
+        return self.probe_inspectors(
+            self.field_inspectors, 'field_to_swagger_object', field, {'field_inspectors': self.field_inspectors},
+            swagger_object_type=swagger_object_type, use_references=use_references, **kwargs
+        )
+
+    def _get_partial_types(self, field, swagger_object_type, use_references, **kwargs):
+        """Helper method to extract generic information from a field and return a partial constructor for the
+        appropriate openapi object.
+
+        All arguments are the same as :meth:`.field_to_swagger_object`.
+
+        The return value is a tuple consisting of:
+
+        * a function for constructing objects of `swagger_object_type`; its prototype is: ::
+
+            def SwaggerType(existing_object=None, **instance_kwargs):
+
+          This function creates an instance of `swagger_object_type`, passing the following attributes to its init,
+          in order of precedence:
+
+            - arguments specified by the ``kwargs`` parameter of :meth:`._get_partial_types`
+            - ``instance_kwargs`` passed to the constructor function
+            - ``title``, ``description``, ``required``, ``x-nullable`` and ``default`` inferred from the field,
+              where appropriate
+
+          If ``existing_object`` is not ``None``, it is updated instead of creating a new object.
+
+        * a type that should be used for child objects if `field` is of an array type. This can currently have two
+          values:
+
+            - :class:`.Schema` if `swagger_object_type` is :class:`.Schema`
+            - :class:`.Items` if `swagger_object_type` is  :class:`.Parameter` or :class:`.Items`
+
+        :rtype: (function,type[openapi.Schema] or type[openapi.Items])
+        """
+        assert swagger_object_type in (openapi.Schema, openapi.Parameter, openapi.Items)
+        assert not isinstance(field, openapi.SwaggerDict), "passed field is already a SwaggerDict object"
+        title = force_real_str(field.label) if field.label else None
+        title = title if swagger_object_type == openapi.Schema else None  # only Schema has title
+        help_text = getattr(field, 'help_text', None)
+        description = force_real_str(help_text) if help_text else None
+        description = description if swagger_object_type != openapi.Items else None  # Items has no description either
+
+        def SwaggerType(existing_object=None, **instance_kwargs):
+            if 'required' not in instance_kwargs and swagger_object_type == openapi.Parameter:
+                instance_kwargs['required'] = field.required
+
+            if 'default' not in instance_kwargs and swagger_object_type != openapi.Items:
+                default = get_field_default(field)
+                if default not in (None, serializers.empty):
+                    instance_kwargs['default'] = default
+
+            if instance_kwargs.get('type', None) != openapi.TYPE_ARRAY:
+                instance_kwargs.setdefault('title', title)
+            if description is not None:
+                instance_kwargs.setdefault('description', description)
+            if field.allow_null and not instance_kwargs.get('required', False) and not field.required:
+                instance_kwargs['x_nullable'] = True
+
+            instance_kwargs.update(kwargs)
+
+            if existing_object is not None:
+                assert isinstance(existing_object, swagger_object_type)
+                for key, val in sorted(instance_kwargs.items()):
+                    setattr(existing_object, key, val)
+                result = existing_object
+            else:
+                result = swagger_object_type(**instance_kwargs)
+
+            # Provide an option to add manual paremeters to a schema
+            # for example, to add examples
+            if swagger_object_type == openapi.Schema:
+                self.add_manual_fields(field, result)
+            return result
+
+        # arrays in Schema have Schema elements, arrays in Parameter and Items have Items elements
+        child_swagger_type = openapi.Schema if swagger_object_type == openapi.Schema else openapi.Items
+        return SwaggerType, child_swagger_type
+
+
+class SerializerInspector(FieldInspector):
+    def get_schema(self, serializer):
+        """Convert a DRF Serializer instance to an :class:`.openapi.Schema`.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `serializer`.
+
+        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
+        :rtype: openapi.Schema
+        """
+        return NotHandled
+
+    def get_request_parameters(self, serializer, in_):
+        """Convert a DRF serializer into a list of :class:`.Parameter`\\ s.
+
+        Should return :data:`.NotHandled` if this inspector does not know how to handle the given `serializer`.
+
+        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
+        :param str in_: the location of the parameters, one of the `openapi.IN_*` constants
+        :rtype: list[openapi.Parameter]
+        """
+        return NotHandled
+
+
+class ViewInspector(BaseInspector):
+    body_methods = ('PUT', 'PATCH', 'POST', 'DELETE')  #: methods that are allowed to have a request body
+
+    #: methods that are assumed to require a request body determined by the view's ``serializer_class``
+    implicit_body_methods = ('PUT', 'PATCH', 'POST')
+
+    #: methods which are assumed to return a list of objects when present on non-detail endpoints
+    implicit_list_response_methods = ('GET',)
+
+    # real values set in __init__ to prevent import errors
+    field_inspectors = []  #:
+    filter_inspectors = []  #:
+    paginator_inspectors = []  #:
+
+    def __init__(self, view, path, method, components, request, overrides):
+        """
+        Inspector class responsible for providing :class:`.Operation` definitions given a view, path and method.
+
+        :param dict overrides: manual overrides as passed to :func:`@swagger_auto_schema <.swagger_auto_schema>`
+        """
+        super(ViewInspector, self).__init__(view, path, method, components, request)
+        self.overrides = overrides
+        self._prepend_inspector_overrides('field_inspectors')
+        self._prepend_inspector_overrides('filter_inspectors')
+        self._prepend_inspector_overrides('paginator_inspectors')
+
+    def _prepend_inspector_overrides(self, inspectors):
+        extra_inspectors = self.overrides.get(inspectors, None)
+        if extra_inspectors:
+            default_inspectors = [insp for insp in getattr(self, inspectors) if insp not in extra_inspectors]
+            setattr(self, inspectors, extra_inspectors + default_inspectors)
+
+    def get_operation(self, operation_keys):
+        """Get an :class:`.Operation` for the given API endpoint (path, method).
+        This includes query, body parameters and response schemas.
+
+        :param tuple[str] operation_keys: an array of keys describing the hierarchical layout of this view in the API;
+          e.g. ``('snippets', 'list')``, ``('snippets', 'retrieve')``, etc.
+        :rtype: openapi.Operation
+        """
+        raise NotImplementedError("ViewInspector must implement get_operation()!")
+
+    def is_list_view(self):
+        """Determine whether this view is a list or a detail view. The difference between the two is that
+        detail views depend on a pk/id path parameter. Note that a non-detail view does not necessarily imply a list
+        reponse (:meth:`.has_list_response`), nor are list responses limited to non-detail views.
+
+        For example, one might have a `/topic/<pk>/posts` endpoint which is a detail view that has a list response.
+
+        :rtype: bool"""
+        return is_list_view(self.path, self.method, self.view)
+
+    def has_list_response(self):
+        """Determine whether this view returns multiple objects. By default this is any non-detail view
+        (see :meth:`.is_list_view`) whose request method is one of :attr:`.implicit_list_response_methods`.
+
+        :rtype: bool
+        """
+        return self.is_list_view() and (self.method.upper() in self.implicit_list_response_methods)
+
+    def should_filter(self):
+        """Determine whether filter backend parameters should be included for this request.
+
+        :rtype: bool
+        """
+        return getattr(self.view, 'filter_backends', None) and self.has_list_response()
+
+    def get_filter_parameters(self):
+        """Return the parameters added to the view by its filter backends.
+
+        :rtype: list[openapi.Parameter]
+        """
+        if not self.should_filter():
+            return []
+
+        fields = []
+        for filter_backend in getattr(self.view, 'filter_backends'):
+            fields += self.probe_inspectors(self.filter_inspectors, 'get_filter_parameters', filter_backend()) or []
+
+        return fields
+
+    def should_page(self):
+        """Determine whether paging parameters and structure should be added to this operation's request and response.
+
+        :rtype: bool
+        """
+        return getattr(self.view, 'paginator', None) and self.has_list_response()
+
+    def get_pagination_parameters(self):
+        """Return the parameters added to the view by its paginator.
+
+        :rtype: list[openapi.Parameter]
+        """
+        if not self.should_page():
+            return []
+
+        return self.probe_inspectors(self.paginator_inspectors, 'get_paginator_parameters',
+                                     getattr(self.view, 'paginator')) or []
+
+    def serializer_to_schema(self, serializer):
+        """Convert a serializer to an OpenAPI :class:`.Schema`.
+
+        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
+        :returns: the converted :class:`.Schema`, or ``None`` in case of an unknown serializer
+        :rtype: openapi.Schema or openapi.SchemaRef
+        """
+        return self.probe_inspectors(
+            self.field_inspectors, 'get_schema', serializer, {'field_inspectors': self.field_inspectors}
+        )
+
+    def serializer_to_parameters(self, serializer, in_):
+        """Convert a serializer to a possibly empty list of :class:`.Parameter`\\ s.
+
+        :param serializers.BaseSerializer serializer: the ``Serializer`` instance
+        :param str in_: the location of the parameters, one of the `openapi.IN_*` constants
+        :rtype: list[openapi.Parameter]
+        """
+        return self.probe_inspectors(
+            self.field_inspectors, 'get_request_parameters', serializer, {'field_inspectors': self.field_inspectors},
+            in_=in_
+        ) or []
+
+    def get_paginated_response(self, response_schema):
+        """Add appropriate paging fields to a response :class:`.Schema`.
+
+        :param openapi.Schema response_schema: the response schema that must be paged.
+        :returns: the paginated response class:`.Schema`, or ``None`` in case of an unknown pagination scheme
+        :rtype: openapi.Schema
+        """
+        return self.probe_inspectors(self.paginator_inspectors, 'get_paginated_response',
+                                     getattr(self.view, 'paginator'), response_schema=response_schema)

src/drf_yasg/inspectors/field.py

@@ -0,0 +1,869 @@
+import datetime
+import inspect
+import logging
+import operator
+import sys
+import uuid
+from collections import OrderedDict
+from decimal import Decimal
+
+from django.core import validators
+from django.db import models
+from rest_framework import serializers
+from rest_framework.settings import api_settings as rest_framework_settings
+
+from .. import openapi
+from ..errors import SwaggerGenerationError
+from ..utils import (
+    decimal_as_float, field_value_to_representation, filter_none, get_serializer_class, get_serializer_ref_name
+)
+from .base import FieldInspector, NotHandled, SerializerInspector, call_view_method
+
+try:
+    import typing
+except ImportError:
+    typing = None
+
+try:
+    from inspect import signature as inspect_signature
+except ImportError:
+    inspect_signature = None
+
+logger = logging.getLogger(__name__)
+
+
+class InlineSerializerInspector(SerializerInspector):
+    """Provides serializer conversions using :meth:`.FieldInspector.field_to_swagger_object`."""
+
+    #: whether to output :class:`.Schema` definitions inline or into the ``definitions`` section
+    use_definitions = False
+
+    def get_schema(self, serializer):
+        return self.probe_field_inspectors(serializer, openapi.Schema, self.use_definitions)
+
+    def add_manual_parameters(self, serializer, parameters):
+        """Add/replace parameters from the given list of automatically generated request parameters. This method
+        is called only when the serializer is converted into a list of parameters for use in a form data request.
+
+        :param serializer: serializer instance
+        :param list[openapi.Parameter] parameters: genereated parameters
+        :return: modified parameters
+        :rtype: list[openapi.Parameter]
+        """
+        return parameters
+
+    def get_request_parameters(self, serializer, in_):
+        fields = getattr(serializer, 'fields', {})
+        parameters = [
+            self.probe_field_inspectors(
+                value, openapi.Parameter, self.use_definitions,
+                name=self.get_parameter_name(key), in_=in_
+            )
+            for key, value
+            in fields.items()
+            if not getattr(value, 'read_only', False)
+        ]
+
+        return self.add_manual_parameters(serializer, parameters)
+
+    def get_property_name(self, field_name):
+        return field_name
+
+    def get_parameter_name(self, field_name):
+        return field_name
+
+    def get_serializer_ref_name(self, serializer):
+        return get_serializer_ref_name(serializer)
+
+    def _has_ref_name(self, serializer):
+        serializer_meta = getattr(serializer, 'Meta', None)
+        return hasattr(serializer_meta, 'ref_name')
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, (serializers.ListSerializer, serializers.ListField)):
+            child_schema = self.probe_field_inspectors(field.child, ChildSwaggerType, use_references)
+            limits = find_limits(field) or {}
+            return SwaggerType(
+                type=openapi.TYPE_ARRAY,
+                items=child_schema,
+                **limits
+            )
+        elif isinstance(field, serializers.Serializer):
+            if swagger_object_type != openapi.Schema:
+                raise SwaggerGenerationError("cannot instantiate nested serializer as " + swagger_object_type.__name__)
+
+            ref_name = self.get_serializer_ref_name(field)
+
+            def make_schema_definition(serializer=field):
+                properties = OrderedDict()
+                required = []
+                for property_name, child in serializer.fields.items():
+                    property_name = self.get_property_name(property_name)
+                    prop_kwargs = {
+                        'read_only': bool(child.read_only) or None
+                    }
+                    prop_kwargs = filter_none(prop_kwargs)
+
+                    child_schema = self.probe_field_inspectors(
+                        child, ChildSwaggerType, use_references, **prop_kwargs
+                    )
+                    properties[property_name] = child_schema
+
+                    if child.required and not getattr(child_schema, 'read_only', False):
+                        required.append(property_name)
+
+                result = SwaggerType(
+                    type=openapi.TYPE_OBJECT,
+                    properties=properties,
+                    required=required or None,
+                )
+                if not ref_name and 'title' in result:
+                    # on an inline model, the title is derived from the field name
+                    # but is visno coverually displayed like the model name, which is confusing
+                    # it is better to just remove title from inline models
+                    del result.title
+
+                setattr(result, '_NP_serializer', get_serializer_class(serializer))
+                return result
+
+            if not ref_name or not use_references:
+                return make_schema_definition()
+
+            definitions = self.components.with_scope(openapi.SCHEMA_DEFINITIONS)
+            actual_schema = definitions.setdefault(ref_name, make_schema_definition)
+            actual_schema._remove_read_only()
+
+            actual_serializer = getattr(actual_schema, '_NP_serializer', None)
+            this_serializer = get_serializer_class(field)
+            if actual_serializer and actual_serializer != this_serializer:  # pragma: no cover
+                explicit_refs = self._has_ref_name(actual_serializer) and self._has_ref_name(this_serializer)
+                if not explicit_refs:
+                    raise SwaggerGenerationError(
+                        "Schema for %s would override distinct serializer %s because they implicitly share the same "
+                        "ref_name; explicitly set the ref_name atribute on both serializers' Meta classes"
+                        % (actual_serializer, this_serializer))
+
+            return openapi.SchemaRef(definitions, ref_name)
+
+        return NotHandled
+
+
+class ReferencingSerializerInspector(InlineSerializerInspector):
+    use_definitions = True
+
+
+def get_queryset_field(queryset, field_name):
+    """Try to get information about a model and model field from a queryset.
+
+    :param queryset: the queryset
+    :param field_name: target field name
+    :returns: the model and target field from the queryset as a 2-tuple; both elements can be ``None``
+    :rtype: tuple
+    """
+    model = getattr(queryset, 'model', None)
+    model_field = get_model_field(model, field_name)
+    return model, model_field
+
+
+def get_model_field(model, field_name):
+    """Try to get the given field from a django db model.
+
+    :param model: the model
+    :param field_name: target field name
+    :return: model field or ``None``
+    """
+    try:
+        if field_name == 'pk':
+            return model._meta.pk
+        else:
+            return model._meta.get_field(field_name)
+    except Exception:  # pragma: no cover
+        return None
+
+
+def get_queryset_from_view(view, serializer=None):
+    """Try to get the queryset of the given view
+
+    :param view: the view instance or class
+    :param serializer: if given, will check that the view's get_serializer_class return matches this serialzier
+    :return: queryset or ``None``
+    """
+    try:
+        queryset = call_view_method(view, 'get_queryset', 'queryset')
+
+        if queryset is not None and serializer is not None:
+            # make sure the view is actually using *this* serializer
+            assert type(serializer) == call_view_method(view, 'get_serializer_class', 'serializer_class')
+
+        return queryset
+    except Exception:  # pragma: no cover
+        return None
+
+
+def get_parent_serializer(field):
+    """Get the nearest parent ``Serializer`` instance for the given field.
+
+    :return: ``Serializer`` or ``None``
+    """
+    while field is not None:
+        if isinstance(field, serializers.Serializer):
+            return field
+
+        field = field.parent
+
+    return None  # pragma: no cover
+
+
+def get_related_model(model, source):
+    """Try to find the other side of a model relationship given the name of a related field.
+
+    :param model: one side of the relationship
+    :param str source: related field name
+    :return: related model or ``None``
+    """
+    try:
+        descriptor = getattr(model, source)
+        try:
+            return descriptor.rel.related_model
+        except Exception:
+            return descriptor.field.remote_field.model
+    except Exception:  # pragma: no cover
+        return None
+
+
+class RelatedFieldInspector(FieldInspector):
+    """Provides conversions for ``RelatedField``\\ s."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, serializers.ManyRelatedField):
+            child_schema = self.probe_field_inspectors(field.child_relation, ChildSwaggerType, use_references)
+            return SwaggerType(
+                type=openapi.TYPE_ARRAY,
+                items=child_schema,
+                unique_items=True,
+            )
+
+        if not isinstance(field, serializers.RelatedField):
+            return NotHandled
+
+        field_queryset = getattr(field, 'queryset', None)
+
+        if isinstance(field, (serializers.PrimaryKeyRelatedField, serializers.SlugRelatedField)):
+            if getattr(field, 'pk_field', ''):
+                # a PrimaryKeyRelatedField can have a `pk_field` attribute which is a
+                # serializer field that will convert the PK value
+                result = self.probe_field_inspectors(field.pk_field, swagger_object_type, use_references, **kwargs)
+                # take the type, format, etc from `pk_field`, and the field-level information
+                # like title, description, default from the PrimaryKeyRelatedField
+                return SwaggerType(existing_object=result)
+
+            target_field = getattr(field, 'slug_field', 'pk')
+            if field_queryset is not None:
+                # if the RelatedField has a queryset, try to get the related model field from there
+                model, model_field = get_queryset_field(field_queryset, target_field)
+            else:
+                # if the RelatedField has no queryset (e.g. read only), try to find the target model
+                # from the view queryset or ModelSerializer model, if present
+                parent_serializer = get_parent_serializer(field)
+
+                serializer_meta = getattr(parent_serializer, 'Meta', None)
+                this_model = getattr(serializer_meta, 'model', None)
+                if not this_model:
+                    view_queryset = get_queryset_from_view(self.view, parent_serializer)
+                    this_model = getattr(view_queryset, 'model', None)
+
+                source = getattr(field, 'source', '') or field.field_name
+                if not source and isinstance(field.parent, serializers.ManyRelatedField):
+                    source = field.parent.field_name
+
+                model = get_related_model(this_model, source)
+                model_field = get_model_field(model, target_field)
+
+            attrs = get_basic_type_info(model_field) or {'type': openapi.TYPE_STRING}
+            return SwaggerType(**attrs)
+        elif isinstance(field, serializers.HyperlinkedRelatedField):
+            return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI)
+
+        return SwaggerType(type=openapi.TYPE_STRING)
+
+
+def find_regex(regex_field):
+    """Given a ``Field``, look for a ``RegexValidator`` and try to extract its pattern and return it as a string.
+
+    :param serializers.Field regex_field: the field instance
+    :return: the extracted pattern, or ``None``
+    :rtype: str
+    """
+    regex_validator = None
+    for validator in regex_field.validators:
+        if isinstance(validator, validators.RegexValidator):
+            if isinstance(validator, validators.URLValidator) or validator == validators.validate_ipv4_address:
+                # skip the default url and IP regexes because they are complex and unhelpful
+                # validate_ipv4_address is a RegexValidator instance in Django 1.11
+                continue
+            if regex_validator is not None:
+                # bail if multiple validators are found - no obvious way to choose
+                return None  # pragma: no cover
+            regex_validator = validator
+
+    # regex_validator.regex should be a compiled re object...
+    try:
+        pattern = getattr(getattr(regex_validator, 'regex', None), 'pattern', None)
+    except Exception:  # pragma: no cover
+        logger.warning('failed to compile regex validator of ' + str(regex_field), exc_info=True)
+        return None
+
+    if pattern:
+        # attempt some basic cleanup to remove regex constructs not supported by JavaScript
+        #  -- swagger uses javascript-style regexes - see https://github.com/swagger-api/swagger-editor/issues/1601
+        if pattern.endswith('\\Z') or pattern.endswith('\\z'):
+            pattern = pattern[:-2] + '$'
+
+    return pattern
+
+
+numeric_fields = (serializers.IntegerField, serializers.FloatField, serializers.DecimalField)
+limit_validators = [
+    # minimum and maximum apply to numbers
+    (validators.MinValueValidator, numeric_fields, 'minimum', operator.__gt__),
+    (validators.MaxValueValidator, numeric_fields, 'maximum', operator.__lt__),
+
+    # minLength and maxLength apply to strings
+    (validators.MinLengthValidator, serializers.CharField, 'min_length', operator.__gt__),
+    (validators.MaxLengthValidator, serializers.CharField, 'max_length', operator.__lt__),
+
+    # minItems and maxItems apply to lists
+    (validators.MinLengthValidator, (serializers.ListField, serializers.ListSerializer), 'min_items', operator.__gt__),
+    (validators.MaxLengthValidator, (serializers.ListField, serializers.ListSerializer), 'max_items', operator.__lt__),
+]
+
+
+def find_limits(field):
+    """Given a ``Field``, look for min/max value/length validators and return appropriate limit validation attributes.
+
+    :param serializers.Field field: the field instance
+    :return: the extracted limits
+    :rtype: OrderedDict
+    """
+    limits = {}
+    applicable_limits = [
+        (validator, attr, improves)
+        for validator, field_class, attr, improves in limit_validators
+        if isinstance(field, field_class)
+    ]
+
+    if isinstance(field, serializers.DecimalField) and not decimal_as_float(field):
+        return limits
+
+    for validator in field.validators:
+        if not hasattr(validator, 'limit_value'):
+            continue
+
+        limit_value = validator.limit_value
+        if isinstance(limit_value, Decimal) and decimal_as_float(field):
+            limit_value = float(limit_value)
+
+        for validator_class, attr, improves in applicable_limits:
+            if isinstance(validator, validator_class):
+                if attr not in limits or improves(limit_value, limits[attr]):
+                    limits[attr] = limit_value
+
+    if hasattr(field, "allow_blank") and not field.allow_blank:
+        if limits.get('min_length', 0) < 1:
+            limits['min_length'] = 1
+
+    return OrderedDict(sorted(limits.items()))
+
+
+def decimal_field_type(field):
+    return openapi.TYPE_NUMBER if decimal_as_float(field) else openapi.TYPE_STRING
+
+def recurse_one_to_one(field, visited_set=None):
+    if visited_set is None:
+        visited_set = set()
+    if field in visited_set:
+        return None #cycle?
+    if isinstance(field, models.OneToOneField):
+        tgt = field.target_field
+        visited_set.add(field)
+        return recurse_one_to_one(tgt, visited_set=visited_set)
+    else:
+        tmp = get_basic_type_info(field)
+        return tmp['type']
+
+model_field_to_basic_type = [
+    (models.OneToOneField, (recurse_one_to_one, None)),
+    (models.AutoField, (openapi.TYPE_INTEGER, None)),
+    (models.BinaryField, (openapi.TYPE_STRING, openapi.FORMAT_BINARY)),
+    (models.BooleanField, (openapi.TYPE_BOOLEAN, None)),
+    (models.NullBooleanField, (openapi.TYPE_BOOLEAN, None)),
+    (models.DateTimeField, (openapi.TYPE_STRING, openapi.FORMAT_DATETIME)),
+    (models.DateField, (openapi.TYPE_STRING, openapi.FORMAT_DATE)),
+    (models.DecimalField, (decimal_field_type, openapi.FORMAT_DECIMAL)),
+    (models.DurationField, (openapi.TYPE_INTEGER, None)),
+    (models.FloatField, (openapi.TYPE_NUMBER, None)),
+    (models.IntegerField, (openapi.TYPE_INTEGER, None)),
+    (models.IPAddressField, (openapi.TYPE_STRING, openapi.FORMAT_IPV4)),
+    (models.GenericIPAddressField, (openapi.TYPE_STRING, openapi.FORMAT_IPV6)),
+    (models.SlugField, (openapi.TYPE_STRING, openapi.FORMAT_SLUG)),
+    (models.TextField, (openapi.TYPE_STRING, None)),
+    (models.TimeField, (openapi.TYPE_STRING, None)),
+    (models.UUIDField, (openapi.TYPE_STRING, openapi.FORMAT_UUID)),
+    (models.CharField, (openapi.TYPE_STRING, None)),
+]
+
+ip_format = {'ipv4': openapi.FORMAT_IPV4, 'ipv6': openapi.FORMAT_IPV6}
+
+serializer_field_to_basic_type = [
+    (serializers.EmailField, (openapi.TYPE_STRING, openapi.FORMAT_EMAIL)),
+    (serializers.SlugField, (openapi.TYPE_STRING, openapi.FORMAT_SLUG)),
+    (serializers.URLField, (openapi.TYPE_STRING, openapi.FORMAT_URI)),
+    (serializers.IPAddressField, (openapi.TYPE_STRING, lambda field: ip_format.get(field.protocol, None))),
+    (serializers.UUIDField, (openapi.TYPE_STRING, openapi.FORMAT_UUID)),
+    (serializers.RegexField, (openapi.TYPE_STRING, None)),
+    (serializers.CharField, (openapi.TYPE_STRING, None)),
+    (serializers.BooleanField, (openapi.TYPE_BOOLEAN, None)),
+    (serializers.NullBooleanField, (openapi.TYPE_BOOLEAN, None)),
+    (serializers.IntegerField, (openapi.TYPE_INTEGER, None)),
+    (serializers.FloatField, (openapi.TYPE_NUMBER, None)),
+    (serializers.DecimalField, (decimal_field_type, openapi.FORMAT_DECIMAL)),
+    (serializers.DurationField, (openapi.TYPE_NUMBER, None)),  # ?
+    (serializers.DateField, (openapi.TYPE_STRING, openapi.FORMAT_DATE)),
+    (serializers.DateTimeField, (openapi.TYPE_STRING, openapi.FORMAT_DATETIME)),
+    (serializers.ModelField, (openapi.TYPE_STRING, None)),
+]
+
+basic_type_info = serializer_field_to_basic_type + model_field_to_basic_type
+
+
+def get_basic_type_info(field):
+    """Given a serializer or model ``Field``, return its basic type information - ``type``, ``format``, ``pattern``,
+    and any applicable min/max limit values.
+
+    :param field: the field instance
+    :return: the extracted attributes as a dictionary, or ``None`` if the field type is not known
+    :rtype: OrderedDict
+    """
+    if field is None:
+        return None
+
+    for field_class, type_format in basic_type_info:
+        if isinstance(field, field_class):
+            swagger_type, format = type_format
+            if callable(swagger_type):
+                swagger_type = swagger_type(field)
+            if callable(format):
+                format = format(field)
+            break
+    else:  # pragma: no cover
+        return None
+
+    pattern = None
+    if swagger_type == openapi.TYPE_STRING:
+        pattern = find_regex(field)
+
+    limits = find_limits(field)
+
+    result = OrderedDict([
+        ('type', swagger_type),
+        ('format', format),
+        ('pattern', pattern)
+    ])
+    result.update(limits)
+    result = filter_none(result)
+    return result
+
+
+def decimal_return_type():
+    return openapi.TYPE_STRING if rest_framework_settings.COERCE_DECIMAL_TO_STRING else openapi.TYPE_NUMBER
+
+
+def get_origin_type(hint_class):
+    return getattr(hint_class, '__origin__', None) or hint_class
+
+
+def hint_class_issubclass(hint_class, check_class):
+    origin_type = get_origin_type(hint_class)
+    return inspect.isclass(origin_type) and issubclass(origin_type, check_class)
+
+
+hinting_type_info = [
+    (bool, (openapi.TYPE_BOOLEAN, None)),
+    (int, (openapi.TYPE_INTEGER, None)),
+    (str, (openapi.TYPE_STRING, None)),
+    (float, (openapi.TYPE_NUMBER, None)),
+    (dict, (openapi.TYPE_OBJECT, None)),
+    (Decimal, (decimal_return_type, openapi.FORMAT_DECIMAL)),
+    (uuid.UUID, (openapi.TYPE_STRING, openapi.FORMAT_UUID)),
+    (datetime.datetime, (openapi.TYPE_STRING, openapi.FORMAT_DATETIME)),
+    (datetime.date, (openapi.TYPE_STRING, openapi.FORMAT_DATE)),
+]
+
+if sys.version_info < (3, 0):
+    # noinspection PyUnresolvedReferences
+    hinting_type_info.append((unicode, (openapi.TYPE_STRING, None)))  # noqa: F821
+
+if typing:
+    def inspect_collection_hint_class(hint_class):
+        args = hint_class.__args__
+        child_class = args[0] if args else str
+        child_type_info = get_basic_type_info_from_hint(child_class) or {'type': openapi.TYPE_STRING}
+
+        return OrderedDict([
+            ('type', openapi.TYPE_ARRAY),
+            ('items', openapi.Items(**child_type_info)),
+        ])
+
+    hinting_type_info.append(((typing.Sequence, typing.AbstractSet), inspect_collection_hint_class))
+
+
+def _get_union_types(hint_class):
+    if typing:
+        origin_type = get_origin_type(hint_class)
+        if origin_type is typing.Union:
+            return hint_class.__args__
+        try:
+            # python 3.5.2 and lower compatibility
+            if issubclass(origin_type, typing.Union):
+                return hint_class.__union_params__
+        except TypeError:
+            pass
+    return None
+
+
+def get_basic_type_info_from_hint(hint_class):
+    """Given a class (eg from a SerializerMethodField's return type hint,
+    return its basic type information - ``type``, ``format``, ``pattern``,
+    and any applicable min/max limit values.
+
+    :param hint_class: the class
+    :return: the extracted attributes as a dictionary, or ``None`` if the field type is not known
+    :rtype: OrderedDict
+    """
+    union_types = _get_union_types(hint_class)
+
+    if typing and union_types:
+        # Optional is implemented as Union[T, None]
+        if len(union_types) == 2 and isinstance(None, union_types[1]):
+            result = get_basic_type_info_from_hint(union_types[0])
+            if result:
+                result['x-nullable'] = True
+
+            return result
+
+        return None
+
+    for check_class, info in hinting_type_info:
+        if hint_class_issubclass(hint_class, check_class):
+            if callable(info):
+                return info(hint_class)
+
+            swagger_type, format = info
+            if callable(swagger_type):
+                swagger_type = swagger_type()
+
+            return OrderedDict([
+                ('type', swagger_type),
+                ('format', format),
+            ])
+
+    return None
+
+
+class SerializerMethodFieldInspector(FieldInspector):
+    """Provides conversion for SerializerMethodField, optionally using information from the swagger_serializer_method
+    decorator.
+    """
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        if not isinstance(field, serializers.SerializerMethodField):
+            return NotHandled
+
+        method = getattr(field.parent, field.method_name)
+        if method is None:
+            return NotHandled
+
+        # attribute added by the swagger_serializer_method decorator
+        serializer = getattr(method, "_swagger_serializer", None)
+
+        if serializer:
+            # in order of preference for description, use:
+            # 1) field.help_text from SerializerMethodField(help_text)
+            # 2) serializer.help_text from swagger_serializer_method(serializer)
+            # 3) method's docstring
+            description = field.help_text
+            if description is None:
+                description = getattr(serializer, 'help_text', None)
+            if description is None:
+                description = method.__doc__
+
+            label = field.label
+            if label is None:
+                label = getattr(serializer, 'label', None)
+
+            if inspect.isclass(serializer):
+                serializer_kwargs = {
+                    "help_text": description,
+                    "label": label,
+                    "read_only": True,
+                }
+
+                serializer = method._swagger_serializer(**serializer_kwargs)
+            else:
+                serializer.help_text = description
+                serializer.label = label
+                serializer.read_only = True
+
+            return self.probe_field_inspectors(serializer, swagger_object_type, use_references, read_only=True)
+        elif typing and inspect_signature:
+            # look for Python 3.5+ style type hinting of the return value
+            hint_class = inspect_signature(method).return_annotation
+
+            if not inspect.isclass(hint_class) and hasattr(hint_class, '__args__'):
+                hint_class = hint_class.__args__[0]
+            if inspect.isclass(hint_class) and not issubclass(hint_class, inspect._empty):
+                type_info = get_basic_type_info_from_hint(hint_class)
+
+                if type_info is not None:
+                    SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type,
+                                                                            use_references, **kwargs)
+                    return SwaggerType(**type_info)
+
+        return NotHandled
+
+
+class SimpleFieldInspector(FieldInspector):
+    """Provides conversions for fields which can be described using just ``type``, ``format``, ``pattern``
+    and min/max validators.
+    """
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        type_info = get_basic_type_info(field)
+        if type_info is None:
+            return NotHandled
+
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+        return SwaggerType(**type_info)
+
+
+class ChoiceFieldInspector(FieldInspector):
+    """Provides conversions for ``ChoiceField`` and ``MultipleChoiceField``."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, serializers.ChoiceField):
+            enum_type = openapi.TYPE_STRING
+            enum_values = []
+            for choice in field.choices.keys():
+                if isinstance(field, serializers.MultipleChoiceField):
+                    choice = field_value_to_representation(field, [choice])[0]
+                else:
+                    choice = field_value_to_representation(field, choice)
+
+                enum_values.append(choice)
+
+            # for ModelSerializer, try to infer the type from the associated model field
+            serializer = get_parent_serializer(field)
+            if isinstance(serializer, serializers.ModelSerializer):
+                model = getattr(getattr(serializer, 'Meta'), 'model')
+                # Use the parent source for nested fields
+                model_field = get_model_field(model, field.source or field.parent.source)
+                # If the field has a base_field its type must be used
+                if getattr(model_field, "base_field", None):
+                    model_field = model_field.base_field
+                if model_field:
+                    model_type = get_basic_type_info(model_field)
+                    if model_type:
+                        enum_type = model_type.get('type', enum_type)
+            else:
+                # Try to infer field type based on enum values
+                enum_value_types = {type(v) for v in enum_values}
+                if len(enum_value_types) == 1:
+                    values_type = get_basic_type_info_from_hint(next(iter(enum_value_types)))
+                    if values_type:
+                        enum_type = values_type.get('type', enum_type)
+
+            if isinstance(field, serializers.MultipleChoiceField):
+                result = SwaggerType(
+                    type=openapi.TYPE_ARRAY,
+                    items=ChildSwaggerType(
+                        type=enum_type,
+                        enum=enum_values
+                    )
+                )
+                if swagger_object_type == openapi.Parameter:
+                    if result['in'] in (openapi.IN_FORM, openapi.IN_QUERY):
+                        result.collection_format = 'multi'
+            else:
+                result = SwaggerType(type=enum_type, enum=enum_values)
+
+            return result
+
+        return NotHandled
+
+
+class FileFieldInspector(FieldInspector):
+    """Provides conversions for ``FileField``\\ s."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, serializers.FileField):
+            # swagger 2.0 does not support specifics about file fields, so ImageFile gets no special treatment
+            # OpenAPI 3.0 does support it, so a future implementation could handle this better
+            err = SwaggerGenerationError("FileField is supported only in a formData Parameter or response Schema")
+            if swagger_object_type == openapi.Schema:
+                # FileField.to_representation returns URL or file name
+                result = SwaggerType(type=openapi.TYPE_STRING, read_only=True)
+                if getattr(field, 'use_url', rest_framework_settings.UPLOADED_FILES_USE_URL):
+                    result.format = openapi.FORMAT_URI
+                return result
+            elif swagger_object_type == openapi.Parameter:
+                param = SwaggerType(type=openapi.TYPE_FILE)
+                if param['in'] != openapi.IN_FORM:
+                    raise err  # pragma: no cover
+                return param
+            else:
+                raise err  # pragma: no cover
+
+        return NotHandled
+
+
+class DictFieldInspector(FieldInspector):
+    """Provides conversion for ``DictField``."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, serializers.DictField) and swagger_object_type == openapi.Schema:
+            child_schema = self.probe_field_inspectors(field.child, ChildSwaggerType, use_references)
+            return SwaggerType(
+                type=openapi.TYPE_OBJECT,
+                additional_properties=child_schema
+            )
+
+        return NotHandled
+
+
+class HiddenFieldInspector(FieldInspector):
+    """Hide ``HiddenField``."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        if isinstance(field, serializers.HiddenField):
+            return None
+
+        return NotHandled
+
+
+class JSONFieldInspector(FieldInspector):
+    """Provides conversion for ``JSONField``."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+
+        if isinstance(field, serializers.JSONField) and swagger_object_type == openapi.Schema:
+            return SwaggerType(type=openapi.TYPE_OBJECT)
+
+        return NotHandled
+
+
+class StringDefaultFieldInspector(FieldInspector):
+    """For otherwise unhandled fields, return them as plain :data:`.TYPE_STRING` objects."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):  # pragma: no cover
+        # TODO unhandled fields: TimeField
+        SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
+        return SwaggerType(type=openapi.TYPE_STRING)
+
+
+try:
+    from djangorestframework_camel_case.parser import CamelCaseJSONParser
+    from djangorestframework_camel_case.render import CamelCaseJSONRenderer
+    from djangorestframework_camel_case.render import camelize
+except ImportError:  # pragma: no cover
+    CamelCaseJSONParser = CamelCaseJSONRenderer = None
+
+    def camelize(data):
+        return data
+
+
+class CamelCaseJSONFilter(FieldInspector):
+    """Converts property names to camelCase if ``djangorestframework_camel_case`` is used."""
+
+    def camelize_string(self, s):
+        """Hack to force ``djangorestframework_camel_case`` to camelize a plain string.
+
+        :param str s: the string
+        :return: camelized string
+        :rtype: str
+        """
+        return next(iter(camelize({s: ''})))
+
+    def camelize_schema(self, schema):
+        """Recursively camelize property names for the given schema using ``djangorestframework_camel_case``.
+        The target schema object must be modified in-place.
+
+        :param openapi.Schema schema: the :class:`.Schema` object
+        """
+        if getattr(schema, 'properties', {}):
+            schema.properties = OrderedDict(
+                (self.camelize_string(key), self.camelize_schema(openapi.resolve_ref(val, self.components)) or val)
+                for key, val in schema.properties.items()
+            )
+
+            if getattr(schema, 'required', []):
+                schema.required = [self.camelize_string(p) for p in schema.required]
+
+    def process_result(self, result, method_name, obj, **kwargs):
+        if isinstance(result, openapi.Schema.OR_REF) and self.is_camel_case():
+            schema = openapi.resolve_ref(result, self.components)
+            self.camelize_schema(schema)
+
+        return result
+
+    if CamelCaseJSONParser and CamelCaseJSONRenderer:
+        def is_camel_case(self):
+            return (
+                any(issubclass(parser, CamelCaseJSONParser) for parser in self.get_parser_classes()) or
+                any(issubclass(renderer, CamelCaseJSONRenderer) for renderer in self.get_renderer_classes())
+            )
+    else:
+        def is_camel_case(self):
+            return False
+
+
+try:
+    from rest_framework_recursive.fields import RecursiveField
+except ImportError:  # pragma: no cover
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+        pass
+else:
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+
+        def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+            if isinstance(field, RecursiveField) and swagger_object_type == openapi.Schema:
+                assert use_references is True, "Can not create schema for RecursiveField when use_references is False"
+
+                proxied = field.proxied
+                if isinstance(field.proxied, serializers.ListSerializer):
+                    proxied = proxied.child
+
+                ref_name = get_serializer_ref_name(proxied)
+                assert ref_name is not None, "Can't create RecursiveField schema for inline " + str(type(proxied))
+
+                definitions = self.components.with_scope(openapi.SCHEMA_DEFINITIONS)
+
+                ref = openapi.SchemaRef(definitions, ref_name, ignore_unresolved=True)
+                if isinstance(field.proxied, serializers.ListSerializer):
+                    ref = openapi.Items(type=openapi.TYPE_ARRAY, items=ref)
+
+                return ref
+
+            return NotHandled

src/drf_yasg/inspectors/query.py

@@ -0,0 +1,84 @@
+from collections import OrderedDict
+
+import coreschema
+from rest_framework.pagination import CursorPagination, LimitOffsetPagination, PageNumberPagination
+
+from .. import openapi
+from ..utils import force_real_str
+from .base import FilterInspector, PaginatorInspector
+
+
+class CoreAPICompatInspector(PaginatorInspector, FilterInspector):
+    """Converts ``coreapi.Field``\\ s to :class:`.openapi.Parameter`\\ s for filters and paginators that implement a
+    ``get_schema_fields`` method.
+    """
+
+    def get_paginator_parameters(self, paginator):
+        fields = []
+        if hasattr(paginator, 'get_schema_fields'):
+            fields = paginator.get_schema_fields(self.view)
+
+        return [self.coreapi_field_to_parameter(field) for field in fields]
+
+    def get_filter_parameters(self, filter_backend):
+        fields = []
+        if hasattr(filter_backend, 'get_schema_fields'):
+            fields = filter_backend.get_schema_fields(self.view)
+        return [self.coreapi_field_to_parameter(field) for field in fields]
+
+    def coreapi_field_to_parameter(self, field):
+        """Convert an instance of `coreapi.Field` to a swagger :class:`.Parameter` object.
+
+        :param coreapi.Field field:
+        :rtype: openapi.Parameter
+        """
+        location_to_in = {
+            'query': openapi.IN_QUERY,
+            'path': openapi.IN_PATH,
+            'form': openapi.IN_FORM,
+            'body': openapi.IN_FORM,
+        }
+        coreapi_types = {
+            coreschema.Integer: openapi.TYPE_INTEGER,
+            coreschema.Number: openapi.TYPE_NUMBER,
+            coreschema.String: openapi.TYPE_STRING,
+            coreschema.Boolean: openapi.TYPE_BOOLEAN,
+        }
+
+        coreschema_attrs = ['format', 'pattern', 'enum', 'min_length', 'max_length']
+        schema = field.schema
+        return openapi.Parameter(
+            name=field.name,
+            in_=location_to_in[field.location],
+            required=field.required,
+            description=force_real_str(schema.description) if schema else None,
+            type=coreapi_types.get(type(schema), openapi.TYPE_STRING),
+            **OrderedDict((attr, getattr(schema, attr, None)) for attr in coreschema_attrs)
+        )
+
+
+class DjangoRestResponsePagination(PaginatorInspector):
+    """Provides response schema pagination warpping for django-rest-framework's LimitOffsetPagination,
+    PageNumberPagination and CursorPagination
+    """
+
+    def get_paginated_response(self, paginator, response_schema):
+        assert response_schema.type == openapi.TYPE_ARRAY, "array return expected for paged response"
+        paged_schema = None
+        if isinstance(paginator, (LimitOffsetPagination, PageNumberPagination, CursorPagination)):
+            has_count = not isinstance(paginator, CursorPagination)
+            paged_schema = openapi.Schema(
+                type=openapi.TYPE_OBJECT,
+                properties=OrderedDict((
+                    ('count', openapi.Schema(type=openapi.TYPE_INTEGER) if has_count else None),
+                    ('next', openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI, x_nullable=True)),
+                    ('previous', openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI, x_nullable=True)),
+                    ('results', response_schema),
+                )),
+                required=['results']
+            )
+
+            if has_count:
+                paged_schema.required.insert(0, 'count')
+
+        return paged_schema

src/drf_yasg/inspectors/view.py

@@ -0,0 +1,406 @@
+import logging
+from collections import OrderedDict
+
+from rest_framework.request import is_form_media_type
+from rest_framework.schemas import AutoSchema
+from rest_framework.status import is_success
+
+from .. import openapi
+from ..errors import SwaggerGenerationError
+from ..utils import (
+    filter_none, force_real_str, force_serializer_instance, get_consumes, get_produces, guess_response_status,
+    merge_params, no_body, param_list_to_odict
+)
+from .base import ViewInspector, call_view_method
+
+logger = logging.getLogger(__name__)
+
+
+class SwaggerAutoSchema(ViewInspector):
+    def __init__(self, view, path, method, components, request, overrides, operation_keys=None):
+        super(SwaggerAutoSchema, self).__init__(view, path, method, components, request, overrides)
+        self._sch = AutoSchema()
+        self._sch.view = view
+        self.operation_keys = operation_keys
+
+    def get_operation(self, operation_keys=None):
+        operation_keys = operation_keys or self.operation_keys
+
+        consumes = self.get_consumes()
+        produces = self.get_produces()
+
+        body = self.get_request_body_parameters(consumes)
+        query = self.get_query_parameters()
+        parameters = body + query
+        parameters = filter_none(parameters)
+        parameters = self.add_manual_parameters(parameters)
+
+        operation_id = self.get_operation_id(operation_keys)
+        summary, description = self.get_summary_and_description()
+        security = self.get_security()
+        assert security is None or isinstance(security, list), "security must be a list of security requirement objects"
+        deprecated = self.is_deprecated()
+        tags = self.get_tags(operation_keys)
+
+        responses = self.get_responses()
+
+        return openapi.Operation(
+            operation_id=operation_id,
+            description=force_real_str(description),
+            summary=force_real_str(summary),
+            responses=responses,
+            parameters=parameters,
+            consumes=consumes,
+            produces=produces,
+            tags=tags,
+            security=security,
+            deprecated=deprecated
+        )
+
+    def get_request_body_parameters(self, consumes):
+        """Return the request body parameters for this view. |br|
+        This is either:
+
+        -  a list with a single object Parameter with a :class:`.Schema` derived from the request serializer
+        -  a list of primitive Parameters parsed as form data
+
+        :param list[str] consumes: a list of accepted MIME types as returned by :meth:`.get_consumes`
+        :return: a (potentially empty) list of :class:`.Parameter`\\ s either ``in: body`` or ``in: formData``
+        :rtype: list[openapi.Parameter]
+        """
+        serializer = self.get_request_serializer()
+        schema = None
+        if serializer is None:
+            return []
+
+        if isinstance(serializer, openapi.Schema.OR_REF):
+            schema = serializer
+
+        if any(is_form_media_type(encoding) for encoding in consumes):
+            if schema is not None:
+                raise SwaggerGenerationError("form request body cannot be a Schema")
+            return self.get_request_form_parameters(serializer)
+        else:
+            if schema is None:
+                schema = self.get_request_body_schema(serializer)
+            return [self.make_body_parameter(schema)] if schema is not None else []
+
+    def get_view_serializer(self):
+        """Return the serializer as defined by the view's ``get_serializer()`` method.
+
+        :return: the view's ``Serializer``
+        :rtype: rest_framework.serializers.Serializer
+        """
+        return call_view_method(self.view, 'get_serializer')
+
+    def _get_request_body_override(self):
+        """Parse the request_body key in the override dict. This method is not public API."""
+        body_override = self.overrides.get('request_body', None)
+
+        if body_override is not None:
+            if body_override is no_body:
+                return no_body
+            if self.method not in self.body_methods:
+                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)
+
+        return body_override
+
+    def get_request_serializer(self):
+        """Return the request serializer (used for parsing the request payload) for this endpoint.
+
+        :return: the request serializer, or one of :class:`.Schema`, :class:`.SchemaRef`, ``None``
+        :rtype: rest_framework.serializers.Serializer
+        """
+        body_override = self._get_request_body_override()
+
+        if body_override is None and self.method in self.implicit_body_methods:
+            return self.get_view_serializer()
+
+        if body_override is no_body:
+            return None
+
+        return body_override
+
+    def get_request_form_parameters(self, serializer):
+        """Given a Serializer, return a list of ``in: formData`` :class:`.Parameter`\\ s.
+
+        :param serializer: the view's request serializer as returned by :meth:`.get_request_serializer`
+        :rtype: list[openapi.Parameter]
+        """
+        return self.serializer_to_parameters(serializer, in_=openapi.IN_FORM)
+
+    def get_request_body_schema(self, serializer):
+        """Return the :class:`.Schema` for a given request's body data. Only applies to PUT, PATCH and POST requests.
+
+        :param serializer: the view's request serializer as returned by :meth:`.get_request_serializer`
+        :rtype: openapi.Schema
+        """
+        return self.serializer_to_schema(serializer)
+
+    def make_body_parameter(self, schema):
+        """Given a :class:`.Schema` object, create an ``in: body`` :class:`.Parameter`.
+
+        :param openapi.Schema schema: the request body schema
+        :rtype: openapi.Parameter
+        """
+        return openapi.Parameter(name='data', in_=openapi.IN_BODY, required=True, schema=schema)
+
+    def add_manual_parameters(self, parameters):
+        """Add/replace parameters from the given list of automatically generated request parameters.
+
+        :param list[openapi.Parameter] parameters: genereated parameters
+        :return: modified parameters
+        :rtype: list[openapi.Parameter]
+        """
+        manual_parameters = self.overrides.get('manual_parameters', None) or []
+
+        if any(param.in_ == openapi.IN_BODY for param in manual_parameters):  # pragma: no cover
+            raise SwaggerGenerationError("specify the body parameter as a Schema or Serializer in request_body")
+        if any(param.in_ == openapi.IN_FORM for param in manual_parameters):  # pragma: no cover
+            has_body_parameter = any(param.in_ == openapi.IN_BODY for param in parameters)
+            if has_body_parameter or not any(is_form_media_type(encoding) for encoding in self.get_consumes()):
+                raise SwaggerGenerationError("cannot add form parameters when the request has a request body; "
+                                             "did you forget to set an appropriate parser class on the view?")
+            if self.method not in self.body_methods:
+                raise SwaggerGenerationError("form parameters can only be applied to "
+                                             "(" + ','.join(self.body_methods) + ") HTTP methods")
+
+        return merge_params(parameters, manual_parameters)
+
+    def get_responses(self):
+        """Get the possible responses for this view as a swagger :class:`.Responses` object.
+
+        :return: the documented responses
+        :rtype: openapi.Responses
+        """
+        response_serializers = self.get_response_serializers()
+        return openapi.Responses(
+            responses=self.get_response_schemas(response_serializers)
+        )
+
+    def get_default_response_serializer(self):
+        """Return the default response serializer for this endpoint. This is derived from either the ``request_body``
+        override or the request serializer (:meth:`.get_view_serializer`).
+
+        :return: response serializer, :class:`.Schema`, :class:`.SchemaRef`, ``None``
+        """
+        body_override = self._get_request_body_override()
+        if body_override and body_override is not no_body:
+            return body_override
+
+        return self.get_view_serializer()
+
+    def get_default_responses(self):
+        """Get the default responses determined for this view from the request serializer and request method.
+
+        :type: dict[str, openapi.Schema]
+        """
+        method = self.method.lower()
+
+        default_status = guess_response_status(method)
+        default_schema = ''
+        if method in ('get', 'post', 'put', 'patch'):
+            default_schema = self.get_default_response_serializer()
+
+        default_schema = default_schema or ''
+        if default_schema and not isinstance(default_schema, openapi.Schema):
+            default_schema = self.serializer_to_schema(default_schema) or ''
+
+        if default_schema:
+            if self.has_list_response():
+                default_schema = openapi.Schema(type=openapi.TYPE_ARRAY, items=default_schema)
+            if self.should_page():
+                default_schema = self.get_paginated_response(default_schema) or default_schema
+
+        return OrderedDict({str(default_status): default_schema})
+
+    def get_response_serializers(self):
+        """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, :class:`.Schema`, :class:`.SchemaRef` or :class:`.Response` objects. See
+        :func:`@swagger_auto_schema <.swagger_auto_schema>` for more details.
+
+        :return: the response serializers
+        :rtype: dict
+        """
+        manual_responses = self.overrides.get('responses', None) or {}
+        manual_responses = OrderedDict((str(sc), resp) for sc, resp in manual_responses.items())
+
+        responses = OrderedDict()
+        if not any(is_success(int(sc)) for sc in manual_responses if sc != 'default'):
+            responses = self.get_default_responses()
+
+        responses.update((str(sc), resp) for sc, resp in manual_responses.items())
+        return responses
+
+    def get_response_schemas(self, response_serializers):
+        """Return the :class:`.openapi.Response` objects calculated for this view.
+
+        :param dict response_serializers: response serializers as returned by :meth:`.get_response_serializers`
+        :return: a dictionary of status code to :class:`.Response` object
+        :rtype: dict[str, openapi.Response]
+        """
+        responses = OrderedDict()
+        for sc, serializer in response_serializers.items():
+            if isinstance(serializer, str):
+                response = openapi.Response(
+                    description=force_real_str(serializer)
+                )
+            elif not serializer:
+                continue
+            elif isinstance(serializer, openapi.Response):
+                response = serializer
+                if hasattr(response, 'schema') and not isinstance(response.schema, openapi.Schema.OR_REF):
+                    serializer = force_serializer_instance(response.schema)
+                    response.schema = self.serializer_to_schema(serializer)
+            elif isinstance(serializer, openapi.Schema.OR_REF):
+                response = openapi.Response(
+                    description='',
+                    schema=serializer,
+                )
+            else:
+                serializer = force_serializer_instance(serializer)
+                response = openapi.Response(
+                    description='',
+                    schema=self.serializer_to_schema(serializer),
+                )
+
+            responses[str(sc)] = response
+
+        return responses
+
+    def get_query_serializer(self):
+        """Return the query serializer (used for parsing query parameters) for this endpoint.
+
+        :return: the query serializer, or ``None``
+        """
+        query_serializer = self.overrides.get('query_serializer', None)
+        if query_serializer is not None:
+            query_serializer = force_serializer_instance(query_serializer)
+        return query_serializer
+
+    def get_query_parameters(self):
+        """Return the query parameters accepted by this view.
+
+        :rtype: list[openapi.Parameter]
+        """
+        natural_parameters = self.get_filter_parameters() + self.get_pagination_parameters()
+
+        query_serializer = self.get_query_serializer()
+        serializer_parameters = []
+        if query_serializer is not None:
+            serializer_parameters = self.serializer_to_parameters(query_serializer, in_=openapi.IN_QUERY)
+
+            if len(set(param_list_to_odict(natural_parameters)) & set(param_list_to_odict(serializer_parameters))) != 0:
+                raise SwaggerGenerationError(
+                    "your query_serializer contains fields that conflict with the "
+                    "filter_backend or paginator_class on the view - %s %s" % (self.method, self.path)
+                )
+
+        return natural_parameters + serializer_parameters
+
+    def get_operation_id(self, operation_keys=None):
+        """Return an unique ID for this operation. The ID must be unique across
+        all :class:`.Operation` objects in the API.
+
+        :param tuple[str] operation_keys: an array of keys derived from the pathdescribing the hierarchical layout
+            of this view in the API; e.g. ``('snippets', 'list')``, ``('snippets', 'retrieve')``, etc.
+        :rtype: str
+        """
+        operation_keys = operation_keys or self.operation_keys
+
+        operation_id = self.overrides.get('operation_id', '')
+        if not operation_id:
+            operation_id = '_'.join(operation_keys)
+        return operation_id
+
+    def split_summary_from_description(self, description):
+        """Decide if and how to split a summary out of the given description. The default implementation
+        uses the first paragraph of the description as a summary if it is less than 120 characters long.
+
+        :param description: the full description to be analyzed
+        :return: summary and description
+        :rtype: (str,str)
+        """
+        # https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
+        summary = None
+        summary_max_len = 120  # OpenAPI 2.0 spec says summary should be under 120 characters
+        sections = description.split('\n\n', 1)
+        if len(sections) == 2:
+            sections[0] = sections[0].strip()
+            if len(sections[0]) < summary_max_len:
+                summary, description = sections
+                description = description.strip()
+
+        return summary, description
+
+    def get_summary_and_description(self):
+        """Return an operation summary and description determined from the view's docstring.
+
+        :return: summary and description
+        :rtype: (str,str)
+        """
+        description = self.overrides.get('operation_description', None)
+        summary = self.overrides.get('operation_summary', None)
+        if description is None:
+            description = self._sch.get_description(self.path, self.method) or ''
+            description = description.strip().replace('\r', '')
+
+            if description and (summary is None):
+                # description from docstring... do summary magic
+                summary, description = self.split_summary_from_description(description)
+
+        return summary, 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 is_deprecated(self):
+        """Return ``True`` if this operation is to be marked as deprecated.
+
+        :return: deprecation status
+        :rtype: bool
+        """
+        return self.overrides.get('deprecated', None)
+
+    def get_tags(self, operation_keys=None):
+        """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. If not provided in overrides,
+        tags will be inferred from the operation url.
+
+        :param tuple[str] operation_keys: an array of keys derived from the pathdescribing the hierarchical layout
+            of this view in the API; e.g. ``('snippets', 'list')``, ``('snippets', 'retrieve')``, etc.
+        :rtype: list[str]
+        """
+        operation_keys = operation_keys or self.operation_keys
+
+        tags = self.overrides.get('tags')
+        if not tags:
+            tags = [operation_keys[0]]
+
+        return tags
+
+    def get_consumes(self):
+        """Return the MIME types this endpoint can consume.
+
+        :rtype: list[str]
+        """
+        return get_consumes(self.get_parser_classes())
+
+    def get_produces(self):
+        """Return the MIME types this endpoint can produce.
+
+        :rtype: list[str]
+        """
+        return get_produces(self.get_renderer_classes())

src/drf_yasg/management/commands/generate_swagger.py

@@ -0,0 +1,163 @@
+import logging
+import os
+
+from django.contrib.auth import get_user_model
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management.base import BaseCommand
+from django.utils.module_loading import import_string
+from rest_framework.settings import api_settings
+from rest_framework.test import APIRequestFactory, force_authenticate
+from rest_framework.views import APIView
+
+from ... import openapi
+from ...app_settings import swagger_settings
+from ...codecs import OpenAPICodecJson, OpenAPICodecYaml
+
+
+class Command(BaseCommand):
+    help = 'Write the Swagger schema to disk in JSON or YAML format.'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            'output_file', metavar='output-file',
+            nargs='?',
+            default='-',
+            type=str,
+            help='Output path for generated swagger document, or "-" for stdout.'
+        )
+        parser.add_argument(
+            '-o', '--overwrite',
+            default=False, action='store_true',
+            help='Overwrite the output file if it already exists. '
+                 'Default behavior is to stop if the output file exists.'
+        )
+        parser.add_argument(
+            '-f', '--format', dest='format',
+            default='', choices=['json', 'yaml'],
+            type=str,
+            help='Output format. If not given, it is guessed from the output file extension and defaults to json.'
+        )
+        parser.add_argument(
+            '-u', '--url', dest='api_url',
+            default='',
+            type=str,
+            help='Base API URL - sets the host and scheme attributes of the generated document.'
+        )
+        parser.add_argument(
+            '-m', '--mock-request', dest='mock',
+            default=False, action='store_true',
+            help='Use a mock request when generating the swagger schema. This is useful if your views or serializers '
+                 'depend on context from a request in order to function.'
+        )
+        parser.add_argument(
+            '--api-version', dest='api_version',
+            type=str,
+            help='Version to use to generate schema. This option implies --mock-request.'
+        )
+        parser.add_argument(
+            '--user', dest='user',
+            help='Username of an existing user to use for mocked authentication. This option implies --mock-request.'
+        )
+        parser.add_argument(
+            '-p', '--private',
+            default=False, action="store_true",
+            help='Hides endpoints not accesible to the target user. If --user is not given, only shows endpoints that '
+                 'are accesible to unauthenticated users.\n'
+                 'This has the same effect as passing public=False to get_schema_view() or '
+                 'OpenAPISchemaGenerator.get_schema().\n'
+                 'This option implies --mock-request.'
+        )
+        parser.add_argument(
+            '-g', '--generator-class', dest='generator_class_name',
+            default='',
+            help='Import string pointing to an OpenAPISchemaGenerator subclass to use for schema generation.'
+        )
+
+    def write_schema(self, schema, stream, format):
+        if format == 'json':
+            codec = OpenAPICodecJson(validators=[], pretty=True)
+            swagger_json = codec.encode(schema).decode('utf-8')
+            stream.write(swagger_json)
+        elif format == 'yaml':
+            codec = OpenAPICodecYaml(validators=[])
+            swagger_yaml = codec.encode(schema).decode('utf-8')
+            # YAML is already pretty!
+            stream.write(swagger_yaml)
+        else:  # pragma: no cover
+            raise ValueError("unknown format %s" % format)
+
+    def get_mock_request(self, url, format, user=None):
+        factory = APIRequestFactory()
+
+        request = factory.get(url + '/swagger.' + format)
+        if user is not None:
+            force_authenticate(request, user=user)
+        request = APIView().initialize_request(request)
+        return request
+
+    def get_schema_generator(self, generator_class_name, api_info, api_version, api_url):
+        generator_class = swagger_settings.DEFAULT_GENERATOR_CLASS
+        if generator_class_name:
+            generator_class = import_string(generator_class_name)
+
+        return generator_class(
+            info=api_info,
+            version=api_version,
+            url=api_url,
+        )
+
+    def get_schema(self, generator, request, public):
+        return generator.get_schema(request=request, public=public)
+
+    def handle(self, output_file, overwrite, format, api_url, mock, api_version, user, private, generator_class_name,
+               *args, **kwargs):
+        # disable logs of WARNING and below
+        logging.disable(logging.WARNING)
+
+        info = getattr(swagger_settings, 'DEFAULT_INFO', None)
+        if not isinstance(info, openapi.Info):
+            raise ImproperlyConfigured(
+                'settings.SWAGGER_SETTINGS["DEFAULT_INFO"] should be an '
+                'import string pointing to an openapi.Info object'
+            )
+
+        if not format:
+            if os.path.splitext(output_file)[1] in ('.yml', '.yaml'):
+                format = 'yaml'
+        format = format or 'json'
+
+        api_url = api_url or swagger_settings.DEFAULT_API_URL
+
+        if user:
+            # Only call get_user_model if --user was passed in order to
+            # avoid crashing if auth is not configured in the project
+            user = get_user_model().objects.get(**{get_user_model().USERNAME_FIELD: user})
+
+        mock = mock or private or (user is not None) or (api_version is not None)
+        if mock and not api_url:
+            raise ImproperlyConfigured(
+                '--mock-request requires an API url; either provide '
+                'the --url argument or set the DEFAULT_API_URL setting'
+            )
+
+        request = None
+        if mock:
+            request = self.get_mock_request(api_url, format, user)
+
+        api_version = api_version or api_settings.DEFAULT_VERSION
+        if request and api_version:
+            request.version = api_version
+
+        generator = self.get_schema_generator(generator_class_name, info, api_version, api_url)
+        schema = self.get_schema(generator, request, not private)
+
+        if output_file == '-':
+            self.write_schema(schema, self.stdout, format)
+        else:
+            # normally this would be easily done with open(mode='x'/'w'),
+            # but python 2 is a pain in the ass as usual
+            # TODO: simplify when dropping support for python 2.7
+            flags = os.O_CREAT | os.O_WRONLY
+            flags = flags | (os.O_TRUNC if overwrite else os.O_EXCL)
+            with os.fdopen(os.open(output_file, flags), "w") as stream:
+                self.write_schema(schema, stream, format)

src/drf_yasg/middleware.py

@@ -13,7 +13,7 @@ class SwaggerExceptionMiddleware(object):
 
     def process_exception(self, request, exception):
         if isinstance(exception, SwaggerValidationError):
-            err = {'errors': {exception.validator_name: str(exception)}}
+            err = {'errors': exception.errors, 'message': str(exception)}
             codec = exception.source_codec
             if isinstance(codec, _OpenAPICodec):
                 err = codec.encode_error(err)

src/drf_yasg/openapi.py

@@ -1,9 +1,24 @@
+import six
+
+import collections
+import logging
+import re
 from collections import OrderedDict
 
 from coreapi.compat import urlparse
-from future.utils import raise_from
+from django.urls import get_script_prefix
+from django.utils.functional import Promise
 from inflection import camelize
 
+from .utils import dict_has_ordered_keys, filter_none, force_real_str
+
+try:
+    from collections import abc as collections_abc
+except ImportError:
+    collections_abc = collections
+
+logger = logging.getLogger(__name__)
+
 TYPE_OBJECT = "object"  #:
 TYPE_STRING = "string"  #:
 TYPE_NUMBER = "number"  #:
@@ -32,6 +47,7 @@ FORMAT_URI = "uri"  #:
 # pulled out of my ass
 FORMAT_UUID = "uuid"  #:
 FORMAT_SLUG = "slug"  #:
+FORMAT_DECIMAL = "decimal"
 
 IN_BODY = 'body'  #:
 IN_PATH = 'path'  #:
@@ -94,8 +110,9 @@ class SwaggerDict(OrderedDict):
             raise AttributeError
         try:
             return self[make_swagger_name(item)]
-        except KeyError as e:
-            raise_from(AttributeError("object of class " + type(self).__name__ + " has no attribute " + item), e)
+        except KeyError:
+            # raise_from is EXTREMELY slow, replaced with plain raise
+            raise AttributeError("object of class " + type(self).__name__ + " has no attribute " + item)
 
     def __delattr__(self, item):
         if item.startswith('_'):
@@ -111,7 +128,7 @@ class SwaggerDict(OrderedDict):
         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.
         """
-        for attr, val in self._extras__.items():
+        for attr, val in sorted(self._extras__.items()):
             setattr(self, attr, val)
 
     @staticmethod
@@ -120,13 +137,22 @@ class SwaggerDict(OrderedDict):
         if id(obj) in memo:
             return memo[id(obj)]
 
-        if isinstance(obj, dict):
+        if isinstance(obj, Promise) and hasattr(obj, '_proxy____cast'):
+            # handle __proxy__ objects from django.utils.functional.lazy
+            obj = obj._proxy____cast()
+
+        if isinstance(obj, collections_abc.Mapping):
             result = OrderedDict()
             memo[id(obj)] = result
-            for attr, val in obj.items():
+            items = obj.items()
+            if not dict_has_ordered_keys(obj):
+                items = sorted(items)
+            for attr, val in items:
                 result[attr] = SwaggerDict._as_odict(val, memo)
             return result
-        elif isinstance(obj, (list, tuple)):
+        elif isinstance(obj, six.string_types):
+            return force_real_str(obj)
+        elif isinstance(obj, collections_abc.Iterable) and not isinstance(obj, collections_abc.Iterator):
             return type(obj)(SwaggerDict._as_odict(elem, memo) for elem in obj)
 
         return obj
@@ -141,7 +167,8 @@ class SwaggerDict(OrderedDict):
     def __reduce__(self):
         # for pickle supprt; this skips calls to all SwaggerDict __init__ methods and relies
         # on the already set attributes instead
-        return _bare_SwaggerDict, (type(self),), vars(self), None, iter(self.items())
+        attrs = {k: v for k, v in vars(self).items() if not k.startswith('_NP_')}
+        return _bare_SwaggerDict, (type(self),), attrs, None, iter(self.items())
 
 
 class Contact(SwaggerDict):
@@ -207,14 +234,21 @@ class Info(SwaggerDict):
 
 
 class Swagger(SwaggerDict):
-    def __init__(self, info=None, _url=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
-        :param str _url: URL used for guessing the API host, scheme and basepath
+        :param str _url: URL used for setting the API host and scheme
+        :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 .Paths paths: paths object
-        :param dict[str,.Schema] definitions: named models
+        :param dict[str,dict] security_definitions: list of supported authentication mechanisms
+        :param list[dict[str,list[str]]] security: authentication mechanisms accepted globally
+        :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
         """
         super(Swagger, self).__init__(**extra)
         self.swagger = '2.0'
@@ -223,22 +257,49 @@ class Swagger(SwaggerDict):
 
         if _url:
             url = urlparse.urlparse(_url)
-            if url.netloc:
-                self.host = url.netloc
-            if url.scheme:
-                self.schemes = [url.scheme]
-        self.base_path = '/'
+            assert url.netloc and url.scheme, "if given, url must have both schema and netloc"
+            self.host = url.netloc
+            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 = definitions
+        self.definitions = filter_none(definitions)
         self._insert_extras__()
 
+    @classmethod
+    def get_base_path(cls, script_prefix, api_prefix):
+        """Determine an appropriate value for ``basePath`` based on the SCRIPT_NAME and the api common prefix.
+
+        :param str script_prefix: script prefix as defined by django ``get_script_prefix``
+        :param str api_prefix: api common prefix
+        :return: joined base path
+        """
+        # avoid double slash when joining script_name with api_prefix
+        if script_prefix and script_prefix.endswith('/'):
+            script_prefix = script_prefix[:-1]
+        if not api_prefix.startswith('/'):
+            api_prefix = '/' + api_prefix
+
+        base_path = script_prefix + api_prefix
+
+        # ensure that the base path has a leading slash and no trailing slash
+        if base_path and base_path.endswith('/'):
+            base_path = base_path[:-1]
+        if not base_path.startswith('/'):
+            base_path = '/' + base_path
+
+        return base_path
+
 
 class Paths(SwaggerDict):
     def __init__(self, paths, **extra):
         """A listing of all the paths in the API.
 
-        :param dict[str,.PathItem] paths:
+        :param dict[str,PathItem] paths:
         """
         super(Paths, self).__init__(**extra)
         for path, path_obj in paths.items():
@@ -249,18 +310,20 @@ class Paths(SwaggerDict):
 
 
 class PathItem(SwaggerDict):
+    OPERATION_NAMES = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch']
+
     def __init__(self, get=None, put=None, post=None, delete=None, options=None,
                  head=None, patch=None, parameters=None, **extra):
         """Information about a single path
 
-        :param .Operation get: operation for GET
-        :param .Operation put: operation for PUT
-        :param .Operation post: operation for POST
-        :param .Operation delete: operation for DELETE
-        :param .Operation options: operation for OPTIONS
-        :param .Operation head: operation for HEAD
-        :param .Operation patch: operation for PATCH
-        :param list[.Parameter] parameters: parameters that apply to all operations
+        :param Operation get: operation for GET
+        :param Operation put: operation for PUT
+        :param Operation post: operation for POST
+        :param Operation delete: operation for DELETE
+        :param Operation options: operation for OPTIONS
+        :param Operation head: operation for HEAD
+        :param Operation patch: operation for PATCH
+        :param list[Parameter] parameters: parameters that apply to all operations
         """
         super(PathItem, self).__init__(**extra)
         self.get = get
@@ -270,34 +333,58 @@ class PathItem(SwaggerDict):
         self.patch = patch
         self.delete = delete
         self.options = options
-        self.parameters = parameters
+        self.parameters = filter_none(parameters)
         self._insert_extras__()
 
+    @property
+    def operations(self):
+        """A list of all standard Operations on this PathItem object. See :attr:`.OPERATION_NAMES`.
+
+        :return: list of (method name, Operation) tuples
+        :rtype: list[tuple[str,Operation]]
+        """
+        return [(k, v) for k, v in self.items() if k in PathItem.OPERATION_NAMES and v]
+
 
 class Operation(SwaggerDict):
-    def __init__(self, operation_id, responses, parameters=None, consumes=None,
-                 produces=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
-        :param .Responses responses: responses returned
-        :param list[.Parameter] parameters: parameters accepted
+        :param Responses responses: responses returned
+        :param list[Parameter] parameters: parameters accepted
         :param list[str] consumes: content types accepted
         :param list[str] produces: content types produced
-        :param str description: operation description
+        :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
+        self.summary = summary
         self.description = description
-        self.parameters = [param for param in parameters if param is not None]
+        self.parameters = filter_none(parameters)
         self.responses = responses
-        self.consumes = consumes
-        self.produces = produces
-        self.tags = tags
+        self.consumes = filter_none(consumes)
+        self.produces = filter_none(produces)
+        self.tags = filter_none(tags)
+        self.security = filter_none(security)
         self._insert_extras__()
 
 
+def _check_type(type, format, enum, pattern, items, _obj_type):
+    if items and type != TYPE_ARRAY:
+        raise AssertionError("items can only be used when type is array")
+    if type == TYPE_ARRAY and not items:
+        raise AssertionError("TYPE_ARRAY requires the items attribute")
+    if pattern and type != TYPE_STRING:
+        raise AssertionError("pattern can only be used when type is string")
+    if (format or enum or pattern) and type in (TYPE_OBJECT, TYPE_ARRAY, None):
+        raise AssertionError("[format, enum, pattern] can only be applied to primitive " + _obj_type)
+
+
 class Items(SwaggerDict):
     def __init__(self, type=None, format=None, enum=None, pattern=None, items=None, **extra):
         """Used when defining an array :class:`.Parameter` to describe the array elements.
@@ -314,13 +401,14 @@ class Items(SwaggerDict):
         self.format = format
         self.enum = enum
         self.pattern = pattern
-        self.items = items
+        self.items_ = items
         self._insert_extras__()
+        _check_type(type, format, enum, pattern, items, self.__class__)
 
 
 class Parameter(SwaggerDict):
     def __init__(self, name, in_, description=None, required=None, schema=None,
-                 type=None, format=None, enum=None, pattern=None, items=None, **extra):
+                 type=None, format=None, enum=None, pattern=None, items=None, default=None, **extra):
         """Describe parameters accepted by an :class:`.Operation`. Each parameter should be a unique combination of
         (`name`, `in_`). ``body`` and ``form`` parameters in the same operation are mutually exclusive.
 
@@ -328,16 +416,16 @@ class Parameter(SwaggerDict):
         :param str in_: parameter location
         :param str description: parameter description
         :param bool required: whether the parameter is required for the operation
-        :param .Schema,.SchemaRef schema: required if `in_` is ``body``
+        :param schema: required if `in_` is ``body``
+        :type schema: Schema or SchemaRef
         :param str type: parameter type; required if `in_` is not ``body``; must not be ``object``
         :param str format: value format, see OpenAPI spec
         :param list enum: restrict possible values
         :param str pattern: pattern if type is ``string``
         :param .Items items: only valid if `type` is ``array``
+        :param default: default value if the parameter is not provided; must conform to parameter type
         """
         super(Parameter, self).__init__(**extra)
-        if (not schema and not type) or (schema and type):
-            raise AssertionError("either schema or type are required for Parameter object!")
         self.name = name
         self.in_ = in_
         self.description = description
@@ -347,47 +435,82 @@ class Parameter(SwaggerDict):
         self.format = format
         self.enum = enum
         self.pattern = pattern
-        self.items = items
+        self.items_ = items
+        self.default = default
         self._insert_extras__()
+        if (not schema and not type) or (schema and type):
+            raise AssertionError("either schema or type are required for Parameter object (not both)!")
+        if schema and isinstance(schema, Schema):
+            schema._remove_read_only()
+        if self['in'] == IN_PATH:
+            # path parameters must always be required
+            assert required is not False, "path parameter cannot be optional"
+            self.required = True
+        if self['in'] != IN_BODY and schema is not None:
+            raise AssertionError("schema can only be applied to a body Parameter, not %s" % type)
+        if default and not type:
+            raise AssertionError("default can only be applied to a non-body Parameter")
+        _check_type(type, format, enum, pattern, items, self.__class__)
 
 
 class Schema(SwaggerDict):
-    OR_REF = ()
+    OR_REF = ()  #: useful for type-checking, e.g ``isinstance(obj, openapi.Schema.OR_REF)``
 
-    def __init__(self, description=None, required=None, type=None, properties=None, additional_properties=None,
-                 format=None, enum=None, pattern=None, items=None, **extra):
+    def __init__(self, title=None, description=None, type=None, format=None, enum=None, pattern=None, properties=None,
+                 additional_properties=None, required=None, items=None, default=None, read_only=None, **extra):
         """Describes a complex object accepted as parameter or returned as a response.
 
-        :param description: schema description
-        :param list[str] required: list of requried property names
+        :param str title: schema title
+        :param str description: schema description
         :param str type: value type; required
-        :param list[.Schema,.SchemaRef] properties: object properties; required if `type` is ``object``
-        :param bool,.Schema,.SchemaRef additional_properties: allow wildcard properties not listed in `properties`
         :param str format: value format, see OpenAPI spec
         :param list enum: restrict possible values
         :param str pattern: pattern if type is ``string``
-        :param .Schema,.SchemaRef items: only valid if `type` is ``array``
+        :param properties: object properties; required if `type` is ``object``
+        :type properties: dict[str,Schema or SchemaRef]
+        :param additional_properties: allow wildcard properties not listed in `properties`
+        :type additional_properties: bool or Schema or SchemaRef
+        :param list[str] required: list of required property names
+        :param items: type of array items, only valid if `type` is ``array``
+        :type items: Schema or SchemaRef
+        :param default: only valid when insider another ``Schema``\\ 's ``properties``;
+            the default value of this property if it is not provided, must conform to the type of this Schema
+        :param read_only: only valid when insider another ``Schema``\\ 's ``properties``;
+            declares the property as read only - it must only be sent as part of responses, never in requests
         """
         super(Schema, self).__init__(**extra)
         if required is True or required is False:
             # common error
-            raise AssertionError(
-                "the `requires` attribute of schema must be an array of required properties, not a boolean!")
-        assert type is not None, "type is required!"
+            raise AssertionError("the `required` attribute of schema must be an "
+                                 "array of required property names, not a boolean!")
+        assert type, "type is required!"
+        self.title = title
         self.description = description
-        self.required = required
+        self.required = filter_none(required)
         self.type = type
-        self.properties = properties
+        self.properties = filter_none(properties)
         self.additional_properties = additional_properties
         self.format = format
         self.enum = enum
         self.pattern = pattern
-        self.items = items
+        self.items_ = items
+        self.read_only = read_only
+        self.default = default
         self._insert_extras__()
+        if (properties or (additional_properties is not None)) and type != TYPE_OBJECT:
+            raise AssertionError("only object Schema can have properties")
+        _check_type(type, format, enum, pattern, items, self.__class__)
+
+    def _remove_read_only(self):
+        # readOnly is only valid for Schemas inside another Schema's properties;
+        # when placing Schema elsewhere we must take care to remove the readOnly flag
+        self.pop('readOnly', '')
 
 
 class _Ref(SwaggerDict):
-    def __init__(self, resolver, name, scope, expected_type):
+    ref_name_re = re.compile(r"#/(?P<scope>.+)/(?P<name>[^/]+)$")
+
+    def __init__(self, resolver, name, scope, expected_type, ignore_unresolved=False):
         """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.
 
@@ -395,44 +518,69 @@ class _Ref(SwaggerDict):
         :param str name: referenced object name, e.g. "Article"
         :param str scope: reference scope, e.g. "definitions"
         :param type[.SwaggerDict] expected_type: the expected type that will be asserted on the object found in resolver
+        :param bool ignore_unresolved: do not throw if the referenced object does not exist
         """
         super(_Ref, self).__init__()
         assert not type(self) == _Ref, "do not instantiate _Ref directly"
         ref_name = "#/{scope}/{name}".format(scope=scope, name=name)
-        obj = resolver.get(name, scope)
-        assert isinstance(obj, expected_type), ref_name + " is a {actual}, not a {expected}" \
-            .format(actual=type(obj).__name__, expected=expected_type.__name__)
+        if not ignore_unresolved:
+            obj = resolver.get(name, scope)
+            assert isinstance(obj, expected_type), ref_name + " is a {actual}, not a {expected}" \
+                .format(actual=type(obj).__name__, expected=expected_type.__name__)
         self.ref = ref_name
 
-    def __setitem__(self, key, value, **kwargs):
+    def resolve(self, resolver):
+        """Get the object targeted by this reference from the given component resolver.
+
+        :param .ReferenceResolver resolver: component resolver which must contain the referneced object
+        :returns: the target object
+        """
+        ref_match = self.ref_name_re.match(self.ref)
+        return resolver.get(ref_match.group('name'), scope=ref_match.group('scope'))
+
+    def __setitem__(self, key, value):
         if key == "$ref":
-            return super(_Ref, self).__setitem__(key, value, **kwargs)
+            return super(_Ref, self).__setitem__(key, value)
         raise NotImplementedError("only $ref can be set on Reference objects (not %s)" % key)
 
-    def __delitem__(self, key, **kwargs):
+    def __delitem__(self, key):
         raise NotImplementedError("cannot delete property of Reference object")
 
 
 class SchemaRef(_Ref):
-    def __init__(self, resolver, schema_name):
+    def __init__(self, resolver, schema_name, ignore_unresolved=False):
         """Adds a reference to a named Schema defined in the ``#/definitions/`` object.
 
         :param .ReferenceResolver resolver: component resolver which must contain the definition
         :param str schema_name: schema name
+        :param bool ignore_unresolved: do not throw if the referenced object does not exist
         """
         assert SCHEMA_DEFINITIONS in resolver.scopes
-        super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema)
+        super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema, ignore_unresolved)
 
 
 Schema.OR_REF = (Schema, SchemaRef)
 
 
+def resolve_ref(ref_or_obj, resolver):
+    """Resolve `ref_or_obj` if it is a reference type. Return it unchaged if not.
+
+    :param ref_or_obj: object to derefernece
+    :type ref_or_obj: SwaggerDict or _Ref
+    :param resolver: component resolver which must contain the referenced object
+    """
+    if isinstance(ref_or_obj, _Ref):
+        return ref_or_obj.resolve(resolver)
+    return ref_or_obj
+
+
 class Responses(SwaggerDict):
     def __init__(self, responses, default=None, **extra):
         """Describes the expected responses of an :class:`.Operation`.
 
-        :param dict[(str,int),.Response] responses: mapping of status code to response definition
-        :param .Response default: description of the response structure to expect if another status code is returned
+        :param responses: mapping of status code to response definition
+        :type responses: dict[str or int,Response]
+        :param Response default: description of the response structure to expect if another status code is returned
         """
         super(Responses, self).__init__(**extra)
         for status, response in responses.items():
@@ -447,7 +595,9 @@ class Response(SwaggerDict):
         """Describes the structure of an operation's response.
 
         :param str description: response description
-        :param .Schema,.SchemaRef schema: sturcture of the response body
+        :param schema: sturcture of the response body
+        :type schema: Schema or SchemaRef or rest_framework.serializers.Serializer
+            or type[rest_framework.serializers.Serializer]
         :param dict examples: example bodies mapped by mime type
         """
         super(Response, self).__init__(**extra)
@@ -455,6 +605,8 @@ class Response(SwaggerDict):
         self.schema = schema
         self.examples = examples
         self._insert_extras__()
+        if schema and isinstance(schema, Schema):
+            schema._remove_read_only()
 
 
 class ReferenceResolver(object):
@@ -466,16 +618,26 @@ class ReferenceResolver(object):
     ::
 
         > components = ReferenceResolver('definitions', 'parameters')
-        > definitions = ReferenceResolver.with_scope('definitions')
+        > definitions = components.with_scope('definitions')
         > definitions.set('Article', Schema(...))
         > print(components)
         {'definitions': OrderedDict([('Article', Schema(...)]), 'parameters': OrderedDict()}
     """
 
-    def __init__(self, *scopes):
+    def __init__(self, *scopes, **kwargs):
         """
         :param str scopes: an enumeration of the valid scopes this resolver will contain
         """
+        force_init = kwargs.pop('force_init', False)
+        if not force_init:
+            raise AssertionError(
+                "Creating an instance of ReferenceResolver almost certainly won't do what you want it to do.\n"
+                "See https://github.com/axnsan12/drf-yasg/issues/211, "
+                "https://github.com/axnsan12/drf-yasg/issues/271, "
+                "https://github.com/axnsan12/drf-yasg/issues/325.\n"
+                "Pass `force_init=True` to override this."
+            )
+
         self._objects = OrderedDict()
         self._force_scope = None
         for scope in scopes:
@@ -483,14 +645,14 @@ class ReferenceResolver(object):
             self._objects[scope] = OrderedDict()
 
     def with_scope(self, scope):
-        """Return a new :class:`.ReferenceResolver` whose scope is defaulted and forced to `scope`.
+        """Return a view into this :class:`.ReferenceResolver` whose scope is defaulted and forced to `scope`.
 
         :param str scope: target scope, must be in this resolver's `scopes`
         :return: the bound resolver
         :rtype: .ReferenceResolver
         """
         assert scope in self.scopes, "unknown scope %s" % scope
-        ret = ReferenceResolver()
+        ret = ReferenceResolver(force_init=True)
         ret._objects = self._objects
         ret._force_scope = scope
         return ret
@@ -518,7 +680,7 @@ class ReferenceResolver(object):
         """Set an object in the given scope only if it does not exist.
 
         :param str name: reference name
-        :param callable maker: object factory, called only if necessary
+        :param function maker: object factory, called only if necessary
         :param str scope: reference scope
         """
         scope = self._check_scope(scope)
@@ -526,8 +688,13 @@ class ReferenceResolver(object):
         ret = self.getdefault(name, None, scope)
         if ret is None:
             ret = maker()
+            value = self.getdefault(name, None, scope)
             assert ret is not None, "maker returned None; referenced objects cannot be None/null"
-            self.set(name, ret, scope)
+            if value is None:
+                self.set(name, ret, scope)
+            elif value != ret:
+                logger.debug("during setdefault, maker for %s inserted a value and returned a different value", name)
+                ret = value
 
         return ret
 

src/drf_yasg/renderers.py

@@ -1,25 +1,39 @@
-from django.shortcuts import render, resolve_url
-from rest_framework.renderers import BaseRenderer
-from rest_framework.utils import json
+import six
 
-from .app_settings import swagger_settings, redoc_settings
-from .codecs import OpenAPICodecJson, VALIDATORS, OpenAPICodecYaml
+from django.shortcuts import resolve_url
+from django.template.loader import render_to_string
+from django.utils.encoding import force_str
+from django.utils.functional import Promise
+from rest_framework.renderers import BaseRenderer, JSONRenderer, TemplateHTMLRenderer
+from rest_framework.utils import encoders, json
+
+from .app_settings import redoc_settings, swagger_settings
+from .codecs import VALIDATORS, OpenAPICodecJson, OpenAPICodecYaml
+from .openapi import Swagger
+from .utils import filter_none
 
 
 class _SpecRenderer(BaseRenderer):
     """Base class for text renderers. Handles encoding and validation."""
-    charset = None
-    validators = ['ssv', 'flex']
+    charset = 'utf-8'
+    validators = []
     codec_class = None
 
     @classmethod
     def with_validators(cls, validators):
-        assert all(vld in VALIDATORS for vld in validators), "allowed validators are" + ", ".join(VALIDATORS)
+        assert all(vld in VALIDATORS for vld in validators), "allowed validators are " + ", ".join(VALIDATORS)
         return type(cls.__name__, (cls,), {'validators': validators})
 
     def render(self, data, media_type=None, renderer_context=None):
         assert self.codec_class, "must override codec_class"
         codec = self.codec_class(self.validators)
+
+        if not isinstance(data, Swagger):  # pragma: no cover
+            # if `swagger` is not a ``Swagger`` object, it means we somehow got a non-success ``Response``
+            # in that case, it's probably better to let the default ``JSONRenderer`` render it
+            # see https://github.com/axnsan12/drf-yasg/issues/58
+            return JSONRenderer().render(data, media_type, renderer_context)
+
         return codec.encode(data)
 
 
@@ -45,38 +59,80 @@ class SwaggerYAMLRenderer(_SpecRenderer):
 
 
 class _UIRenderer(BaseRenderer):
-    """Base class for web UI renderers. Handles loading an passing settings to the appropriate template."""
+    """Base class for web UI renderers. Handles loading and passing settings to the appropriate template."""
     media_type = 'text/html'
     charset = 'utf-8'
     template = ''
 
     def render(self, swagger, accepted_media_type=None, renderer_context=None):
-        self.set_context(renderer_context, swagger)
-        return render(
-            renderer_context['request'],
-            self.template,
-            renderer_context
-        )
+        if not isinstance(swagger, Swagger):  # pragma: no cover
+            # if `swagger` is not a ``Swagger`` object, it means we somehow got a non-success ``Response``
+            # in that case, it's probably better to let the default ``TemplateHTMLRenderer`` render it
+            # see https://github.com/axnsan12/drf-yasg/issues/58
+            return TemplateHTMLRenderer().render(swagger, accepted_media_type, renderer_context)
 
-    def set_context(self, renderer_context, swagger):
-        renderer_context['title'] = swagger.info.title
-        renderer_context['version'] = swagger.info.version
-        renderer_context['swagger_settings'] = json.dumps(self.get_swagger_ui_settings())
-        renderer_context['redoc_settings'] = json.dumps(self.get_redoc_settings())
+        self.set_context(renderer_context, swagger)
+        return render_to_string(self.template, renderer_context, renderer_context['request'])
+
+    def set_context(self, renderer_context, swagger=None):
+        renderer_context['title'] = swagger.info.title or '' if swagger else ''
+        renderer_context['version'] = swagger.info.version or '' if swagger else ''
+        renderer_context['oauth2_config'] = json.dumps(self.get_oauth2_config(), cls=encoders.JSONEncoder)
         renderer_context['USE_SESSION_AUTH'] = swagger_settings.USE_SESSION_AUTH
         renderer_context.update(self.get_auth_urls())
 
-    def get_auth_urls(self):
-        urls = {}
-        if swagger_settings.LOGIN_URL is not None:
-            urls['LOGIN_URL'] = resolve_url(swagger_settings.LOGIN_URL)
-        if swagger_settings.LOGOUT_URL is not None:
-            urls['LOGOUT_URL'] = resolve_url(swagger_settings.LOGOUT_URL)
+    def resolve_url(self, to):
+        if isinstance(to, Promise):
+            to = str(to)
 
-        return urls
+        if to is None:
+            return None
+
+        args, kwargs = None, None
+        if not isinstance(to, six.string_types):
+            if len(to) > 2:
+                to, args, kwargs = to
+            elif len(to) == 2:
+                to, kwargs = to
+
+        args = args or ()
+        kwargs = kwargs or {}
+
+        return resolve_url(to, *args, **kwargs)
+
+    def get_auth_urls(self):
+        urls = {
+            'LOGIN_URL': self.resolve_url(swagger_settings.LOGIN_URL),
+            'LOGOUT_URL': self.resolve_url(swagger_settings.LOGOUT_URL),
+        }
+
+        return filter_none(urls)
+
+    def get_oauth2_config(self):
+        data = swagger_settings.OAUTH2_CONFIG
+        assert isinstance(data, dict), "OAUTH2_CONFIG must be a dict"
+        return data
+
+
+class SwaggerUIRenderer(_UIRenderer):
+    """Renders a swagger-ui web interface for schema browisng."""
+    template = 'drf-yasg/swagger-ui.html'
+    format = 'swagger'
+
+    def set_context(self, renderer_context, swagger=None):
+        super(SwaggerUIRenderer, self).set_context(renderer_context, swagger)
+        swagger_ui_settings = self.get_swagger_ui_settings()
+
+        request = renderer_context.get('request', None)
+        oauth_redirect_url = force_str(swagger_ui_settings.get('oauth2RedirectUrl', ''))
+        if request and oauth_redirect_url:
+            swagger_ui_settings['oauth2RedirectUrl'] = request.build_absolute_uri(oauth_redirect_url)
+
+        renderer_context['swagger_settings'] = json.dumps(swagger_ui_settings, cls=encoders.JSONEncoder)
 
     def get_swagger_ui_settings(self):
         data = {
+            'url': self.resolve_url(swagger_settings.SPEC_URL),
             'operationsSorter': swagger_settings.OPERATIONS_SORTER,
             'tagsSorter': swagger_settings.TAGS_SORTER,
             'docExpansion': swagger_settings.DOC_EXPANSION,
@@ -85,35 +141,47 @@ class _UIRenderer(BaseRenderer):
             'defaultModelRendering': swagger_settings.DEFAULT_MODEL_RENDERING,
             'defaultModelExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
             'defaultModelsExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
+            'showCommonExtensions': swagger_settings.SHOW_COMMON_EXTENSIONS,
+            'oauth2RedirectUrl': swagger_settings.OAUTH2_REDIRECT_URL,
+            'supportedSubmitMethods': swagger_settings.SUPPORTED_SUBMIT_METHODS,
+            'displayOperationId': swagger_settings.DISPLAY_OPERATION_ID,
+            'persistAuth': swagger_settings.PERSIST_AUTH,
+            'refetchWithAuth': swagger_settings.REFETCH_SCHEMA_WITH_AUTH,
+            'refetchOnLogout': swagger_settings.REFETCH_SCHEMA_ON_LOGOUT,
+            'fetchSchemaWithQuery': swagger_settings.FETCH_SCHEMA_WITH_QUERY,
         }
-        data = {k: v for k, v in data.items() if v is not None}
+
+        data = filter_none(data)
         if swagger_settings.VALIDATOR_URL != '':
-            data['validatorUrl'] = swagger_settings.VALIDATOR_URL
+            data['validatorUrl'] = self.resolve_url(swagger_settings.VALIDATOR_URL)
 
         return data
 
-    def get_redoc_settings(self):
-        data = {
-            'lazyRendering': redoc_settings.LAZY_RENDERING,
-            'hideHostname': redoc_settings.HIDE_HOSTNAME,
-            'expandResponses': redoc_settings.EXPAND_RESPONSES,
-            'pathInMiddle': redoc_settings.PATH_IN_MIDDLE,
-        }
-
-        return data
-
-
-class SwaggerUIRenderer(_UIRenderer):
-    """Renders a swagger-ui web interface for schema browisng.
-    Also requires :class:`.OpenAPIRenderer` as an available renderer on the same view.
-    """
-    template = 'drf-yasg/swagger-ui.html'
-    format = 'swagger'
-
 
 class ReDocRenderer(_UIRenderer):
-    """Renders a ReDoc web interface for schema browisng.
-    Also requires :class:`.OpenAPIRenderer` as an available renderer on the same view.
-    """
+    """Renders a ReDoc web interface for schema browisng."""
     template = 'drf-yasg/redoc.html'
     format = 'redoc'
+
+    def set_context(self, renderer_context, swagger=None):
+        super(ReDocRenderer, self).set_context(renderer_context, swagger)
+        renderer_context['redoc_settings'] = json.dumps(self.get_redoc_settings(), cls=encoders.JSONEncoder)
+
+    def get_redoc_settings(self):
+        data = {
+            'url': self.resolve_url(redoc_settings.SPEC_URL),
+            'lazyRendering': redoc_settings.LAZY_RENDERING,
+            'hideHostname': redoc_settings.HIDE_HOSTNAME,
+            'expandResponses': redoc_settings.EXPAND_RESPONSES,
+            'pathInMiddlePanel': redoc_settings.PATH_IN_MIDDLE,
+            'nativeScrollbars': redoc_settings.NATIVE_SCROLLBARS,
+            'requiredPropsFirst': redoc_settings.REQUIRED_PROPS_FIRST,
+            'fetchSchemaWithQuery': redoc_settings.FETCH_SCHEMA_WITH_QUERY,
+        }
+
+        return filter_none(data)
+
+
+class ReDocOldRenderer(ReDocRenderer):
+    """Renders a ReDoc 1.x.x web interface for schema browisng."""
+    template = 'drf-yasg/redoc-old.html'

src/drf_yasg/static/drf-yasg/immutable.min.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?module.exports=e():"function"==typeof define&&define.amd?define(e):t.Immutable=e()}(this,function(){"use strict";function t(t,e){e&&(t.prototype=Object.create(e.prototype)),t.prototype.constructor=t}function e(t){return o(t)?t:O(t)}function r(t){return u(t)?t:x(t)}function n(t){return s(t)?t:k(t)}function i(t){return o(t)&&!a(t)?t:A(t)}function o(t){return!(!t||!t[ar])}function u(t){return!(!t||!t[hr])}function s(t){return!(!t||!t[fr])}function a(t){return u(t)||s(t)}function h(t){return!(!t||!t[cr])}function f(t){return t.value=!1,t}function c(t){t&&(t.value=!0)}function _(){}function p(t,e){e=e||0;for(var r=Math.max(0,t.length-e),n=Array(r),i=0;r>i;i++)n[i]=t[i+e];return n}function v(t){return void 0===t.size&&(t.size=t.__iterate(y)),t.size}function l(t,e){if("number"!=typeof e){var r=e>>>0;if(""+r!==e||4294967295===r)return NaN;e=r}return 0>e?v(t)+e:e}function y(){return!0}function d(t,e,r){return(0===t||void 0!==r&&-r>=t)&&(void 0===e||void 0!==r&&e>=r)}function m(t,e){return w(t,e,0)}function g(t,e){return w(t,e,e)}function w(t,e,r){return void 0===t?r:0>t?Math.max(0,e+t):void 0===e?t:Math.min(e,t)}function S(t){this.next=t}function z(t,e,r,n){var i=0===t?e:1===t?r:[e,r];return n?n.value=i:n={value:i,done:!1},n}function I(){return{value:void 0,done:!0}}function b(t){return!!M(t)}function q(t){return t&&"function"==typeof t.next}function D(t){var e=M(t);return e&&e.call(t)}function M(t){var e=t&&(zr&&t[zr]||t[Ir]);return"function"==typeof e?e:void 0}function E(t){return t&&"number"==typeof t.length}function O(t){return null===t||void 0===t?T():o(t)?t.toSeq():C(t)}function x(t){return null===t||void 0===t?T().toKeyedSeq():o(t)?u(t)?t.toSeq():t.fromEntrySeq():B(t)}function k(t){return null===t||void 0===t?T():o(t)?u(t)?t.entrySeq():t.toIndexedSeq():W(t)}function A(t){return(null===t||void 0===t?T():o(t)?u(t)?t.entrySeq():t:W(t)).toSetSeq()}function j(t){this._array=t,this.size=t.length}function R(t){var e=Object.keys(t);this._object=t,this._keys=e,
+this.size=e.length}function U(t){this._iterable=t,this.size=t.length||t.size}function K(t){this._iterator=t,this._iteratorCache=[]}function L(t){return!(!t||!t[qr])}function T(){return Dr||(Dr=new j([]))}function B(t){var e=Array.isArray(t)?new j(t).fromEntrySeq():q(t)?new K(t).fromEntrySeq():b(t)?new U(t).fromEntrySeq():"object"==typeof t?new R(t):void 0;if(!e)throw new TypeError("Expected Array or iterable object of [k, v] entries, or keyed object: "+t);return e}function W(t){var e=J(t);if(!e)throw new TypeError("Expected Array or iterable object of values: "+t);return e}function C(t){var e=J(t)||"object"==typeof t&&new R(t);if(!e)throw new TypeError("Expected Array or iterable object of values, or keyed object: "+t);return e}function J(t){return E(t)?new j(t):q(t)?new K(t):b(t)?new U(t):void 0}function N(t,e,r,n){var i=t._cache;if(i){for(var o=i.length-1,u=0;o>=u;u++){var s=i[r?o-u:u];if(e(s[1],n?s[0]:u,t)===!1)return u+1}return u}return t.__iterateUncached(e,r)}function P(t,e,r,n){var i=t._cache;if(i){var o=i.length-1,u=0;return new S(function(){var t=i[r?o-u:u];return u++>o?I():z(e,n?t[0]:u-1,t[1])})}return t.__iteratorUncached(e,r)}function H(t,e){return e?V(e,t,"",{"":t}):Y(t)}function V(t,e,r,n){return Array.isArray(e)?t.call(n,r,k(e).map(function(r,n){return V(t,r,n,e)})):Q(e)?t.call(n,r,x(e).map(function(r,n){return V(t,r,n,e)})):e}function Y(t){return Array.isArray(t)?k(t).map(Y).toList():Q(t)?x(t).map(Y).toMap():t}function Q(t){return t&&(t.constructor===Object||void 0===t.constructor)}function X(t,e){if(t===e||t!==t&&e!==e)return!0;if(!t||!e)return!1;if("function"==typeof t.valueOf&&"function"==typeof e.valueOf){if(t=t.valueOf(),e=e.valueOf(),t===e||t!==t&&e!==e)return!0;if(!t||!e)return!1}return"function"==typeof t.equals&&"function"==typeof e.equals&&t.equals(e)?!0:!1}function F(t,e){if(t===e)return!0;if(!o(e)||void 0!==t.size&&void 0!==e.size&&t.size!==e.size||void 0!==t.__hash&&void 0!==e.__hash&&t.__hash!==e.__hash||u(t)!==u(e)||s(t)!==s(e)||h(t)!==h(e))return!1;if(0===t.size&&0===e.size)return!0;
+var r=!a(t);if(h(t)){var n=t.entries();return e.every(function(t,e){var i=n.next().value;return i&&X(i[1],t)&&(r||X(i[0],e))})&&n.next().done}var i=!1;if(void 0===t.size)if(void 0===e.size)"function"==typeof t.cacheResult&&t.cacheResult();else{i=!0;var f=t;t=e,e=f}var c=!0,_=e.__iterate(function(e,n){return(r?t.has(e):i?X(e,t.get(n,yr)):X(t.get(n,yr),e))?void 0:(c=!1,!1)});return c&&t.size===_}function G(t,e){if(!(this instanceof G))return new G(t,e);if(this._value=t,this.size=void 0===e?1/0:Math.max(0,e),0===this.size){if(Mr)return Mr;Mr=this}}function Z(t,e){if(!t)throw Error(e)}function $(t,e,r){if(!(this instanceof $))return new $(t,e,r);if(Z(0!==r,"Cannot step a Range by 0"),t=t||0,void 0===e&&(e=1/0),r=void 0===r?1:Math.abs(r),t>e&&(r=-r),this._start=t,this._end=e,this._step=r,this.size=Math.max(0,Math.ceil((e-t)/r-1)+1),0===this.size){if(Er)return Er;Er=this}}function tt(){throw TypeError("Abstract")}function et(){}function rt(){}function nt(){}function it(t){return t>>>1&1073741824|3221225471&t}function ot(t){if(t===!1||null===t||void 0===t)return 0;if("function"==typeof t.valueOf&&(t=t.valueOf(),t===!1||null===t||void 0===t))return 0;if(t===!0)return 1;var e=typeof t;if("number"===e){if(t!==t||t===1/0)return 0;var r=0|t;for(r!==t&&(r^=4294967295*t);t>4294967295;)t/=4294967295,r^=t;return it(r)}if("string"===e)return t.length>Kr?ut(t):st(t);if("function"==typeof t.hashCode)return t.hashCode();if("object"===e)return at(t);if("function"==typeof t.toString)return st(""+t);throw Error("Value type "+e+" cannot be hashed.")}function ut(t){var e=Br[t];return void 0===e&&(e=st(t),Tr===Lr&&(Tr=0,Br={}),Tr++,Br[t]=e),e}function st(t){for(var e=0,r=0;t.length>r;r++)e=31*e+t.charCodeAt(r)|0;return it(e)}function at(t){var e;if(jr&&(e=Or.get(t),void 0!==e))return e;if(e=t[Ur],void 0!==e)return e;if(!Ar){if(e=t.propertyIsEnumerable&&t.propertyIsEnumerable[Ur],void 0!==e)return e;if(e=ht(t),void 0!==e)return e}if(e=++Rr,1073741824&Rr&&(Rr=0),jr)Or.set(t,e);else{if(void 0!==kr&&kr(t)===!1)throw Error("Non-extensible objects are not allowed as keys.");
+if(Ar)Object.defineProperty(t,Ur,{enumerable:!1,configurable:!1,writable:!1,value:e});else if(void 0!==t.propertyIsEnumerable&&t.propertyIsEnumerable===t.constructor.prototype.propertyIsEnumerable)t.propertyIsEnumerable=function(){return this.constructor.prototype.propertyIsEnumerable.apply(this,arguments)},t.propertyIsEnumerable[Ur]=e;else{if(void 0===t.nodeType)throw Error("Unable to set a non-enumerable property on object.");t[Ur]=e}}return e}function ht(t){if(t&&t.nodeType>0)switch(t.nodeType){case 1:return t.uniqueID;case 9:return t.documentElement&&t.documentElement.uniqueID}}function ft(t){Z(t!==1/0,"Cannot perform this action with an infinite size.")}function ct(t){return null===t||void 0===t?zt():_t(t)&&!h(t)?t:zt().withMutations(function(e){var n=r(t);ft(n.size),n.forEach(function(t,r){return e.set(r,t)})})}function _t(t){return!(!t||!t[Wr])}function pt(t,e){this.ownerID=t,this.entries=e}function vt(t,e,r){this.ownerID=t,this.bitmap=e,this.nodes=r}function lt(t,e,r){this.ownerID=t,this.count=e,this.nodes=r}function yt(t,e,r){this.ownerID=t,this.keyHash=e,this.entries=r}function dt(t,e,r){this.ownerID=t,this.keyHash=e,this.entry=r}function mt(t,e,r){this._type=e,this._reverse=r,this._stack=t._root&&wt(t._root)}function gt(t,e){return z(t,e[0],e[1])}function wt(t,e){return{node:t,index:0,__prev:e}}function St(t,e,r,n){var i=Object.create(Cr);return i.size=t,i._root=e,i.__ownerID=r,i.__hash=n,i.__altered=!1,i}function zt(){return Jr||(Jr=St(0))}function It(t,e,r){var n,i;if(t._root){var o=f(dr),u=f(mr);if(n=bt(t._root,t.__ownerID,0,void 0,e,r,o,u),!u.value)return t;i=t.size+(o.value?r===yr?-1:1:0)}else{if(r===yr)return t;i=1,n=new pt(t.__ownerID,[[e,r]])}return t.__ownerID?(t.size=i,t._root=n,t.__hash=void 0,t.__altered=!0,t):n?St(i,n):zt()}function bt(t,e,r,n,i,o,u,s){return t?t.update(e,r,n,i,o,u,s):o===yr?t:(c(s),c(u),new dt(e,n,[i,o]))}function qt(t){return t.constructor===dt||t.constructor===yt}function Dt(t,e,r,n,i){if(t.keyHash===n)return new yt(e,n,[t.entry,i]);var o,u=(0===r?t.keyHash:t.keyHash>>>r)&lr,s=(0===r?n:n>>>r)&lr,a=u===s?[Dt(t,e,r+pr,n,i)]:(o=new dt(e,n,i),
+s>u?[t,o]:[o,t]);return new vt(e,1<<u|1<<s,a)}function Mt(t,e,r,n){t||(t=new _);for(var i=new dt(t,ot(r),[r,n]),o=0;e.length>o;o++){var u=e[o];i=i.update(t,0,void 0,u[0],u[1])}return i}function Et(t,e,r,n){for(var i=0,o=0,u=Array(r),s=0,a=1,h=e.length;h>s;s++,a<<=1){var f=e[s];void 0!==f&&s!==n&&(i|=a,u[o++]=f)}return new vt(t,i,u)}function Ot(t,e,r,n,i){for(var o=0,u=Array(vr),s=0;0!==r;s++,r>>>=1)u[s]=1&r?e[o++]:void 0;return u[n]=i,new lt(t,o+1,u)}function xt(t,e,n){for(var i=[],u=0;n.length>u;u++){var s=n[u],a=r(s);o(s)||(a=a.map(function(t){return H(t)})),i.push(a)}return jt(t,e,i)}function kt(t,e,r){return t&&t.mergeDeep&&o(e)?t.mergeDeep(e):X(t,e)?t:e}function At(t){return function(e,r,n){if(e&&e.mergeDeepWith&&o(r))return e.mergeDeepWith(t,r);var i=t(e,r,n);return X(e,i)?e:i}}function jt(t,e,r){return r=r.filter(function(t){return 0!==t.size}),0===r.length?t:0!==t.size||t.__ownerID||1!==r.length?t.withMutations(function(t){for(var n=e?function(r,n){t.update(n,yr,function(t){return t===yr?r:e(t,r,n)})}:function(e,r){t.set(r,e)},i=0;r.length>i;i++)r[i].forEach(n)}):t.constructor(r[0])}function Rt(t,e,r,n){var i=t===yr,o=e.next();if(o.done){var u=i?r:t,s=n(u);return s===u?t:s}Z(i||t&&t.set,"invalid keyPath");var a=o.value,h=i?yr:t.get(a,yr),f=Rt(h,e,r,n);return f===h?t:f===yr?t.remove(a):(i?zt():t).set(a,f)}function Ut(t){return t-=t>>1&1431655765,t=(858993459&t)+(t>>2&858993459),t=t+(t>>4)&252645135,t+=t>>8,t+=t>>16,127&t}function Kt(t,e,r,n){var i=n?t:p(t);return i[e]=r,i}function Lt(t,e,r,n){var i=t.length+1;if(n&&e+1===i)return t[e]=r,t;for(var o=Array(i),u=0,s=0;i>s;s++)s===e?(o[s]=r,u=-1):o[s]=t[s+u];return o}function Tt(t,e,r){var n=t.length-1;if(r&&e===n)return t.pop(),t;for(var i=Array(n),o=0,u=0;n>u;u++)u===e&&(o=1),i[u]=t[u+o];return i}function Bt(t){var e=Pt();if(null===t||void 0===t)return e;if(Wt(t))return t;var r=n(t),i=r.size;return 0===i?e:(ft(i),i>0&&vr>i?Nt(0,i,pr,null,new Ct(r.toArray())):e.withMutations(function(t){t.setSize(i),r.forEach(function(e,r){return t.set(r,e)})}))}function Wt(t){
+return!(!t||!t[Vr])}function Ct(t,e){this.array=t,this.ownerID=e}function Jt(t,e){function r(t,e,r){return 0===e?n(t,r):i(t,e,r)}function n(t,r){var n=r===s?a&&a.array:t&&t.array,i=r>o?0:o-r,h=u-r;return h>vr&&(h=vr),function(){if(i===h)return Xr;var t=e?--h:i++;return n&&n[t]}}function i(t,n,i){var s,a=t&&t.array,h=i>o?0:o-i>>n,f=(u-i>>n)+1;return f>vr&&(f=vr),function(){for(;;){if(s){var t=s();if(t!==Xr)return t;s=null}if(h===f)return Xr;var o=e?--f:h++;s=r(a&&a[o],n-pr,i+(o<<n))}}}var o=t._origin,u=t._capacity,s=Gt(u),a=t._tail;return r(t._root,t._level,0)}function Nt(t,e,r,n,i,o,u){var s=Object.create(Yr);return s.size=e-t,s._origin=t,s._capacity=e,s._level=r,s._root=n,s._tail=i,s.__ownerID=o,s.__hash=u,s.__altered=!1,s}function Pt(){return Qr||(Qr=Nt(0,0,pr))}function Ht(t,e,r){if(e=l(t,e),e!==e)return t;if(e>=t.size||0>e)return t.withMutations(function(t){0>e?Xt(t,e).set(0,r):Xt(t,0,e+1).set(e,r)});e+=t._origin;var n=t._tail,i=t._root,o=f(mr);return e>=Gt(t._capacity)?n=Vt(n,t.__ownerID,0,e,r,o):i=Vt(i,t.__ownerID,t._level,e,r,o),o.value?t.__ownerID?(t._root=i,t._tail=n,t.__hash=void 0,t.__altered=!0,t):Nt(t._origin,t._capacity,t._level,i,n):t}function Vt(t,e,r,n,i,o){var u=n>>>r&lr,s=t&&t.array.length>u;if(!s&&void 0===i)return t;var a;if(r>0){var h=t&&t.array[u],f=Vt(h,e,r-pr,n,i,o);return f===h?t:(a=Yt(t,e),a.array[u]=f,a)}return s&&t.array[u]===i?t:(c(o),a=Yt(t,e),void 0===i&&u===a.array.length-1?a.array.pop():a.array[u]=i,a)}function Yt(t,e){return e&&t&&e===t.ownerID?t:new Ct(t?t.array.slice():[],e)}function Qt(t,e){if(e>=Gt(t._capacity))return t._tail;if(1<<t._level+pr>e){for(var r=t._root,n=t._level;r&&n>0;)r=r.array[e>>>n&lr],n-=pr;return r}}function Xt(t,e,r){void 0!==e&&(e=0|e),void 0!==r&&(r=0|r);var n=t.__ownerID||new _,i=t._origin,o=t._capacity,u=i+e,s=void 0===r?o:0>r?o+r:i+r;if(u===i&&s===o)return t;if(u>=s)return t.clear();for(var a=t._level,h=t._root,f=0;0>u+f;)h=new Ct(h&&h.array.length?[void 0,h]:[],n),a+=pr,f+=1<<a;f&&(u+=f,i+=f,s+=f,o+=f);for(var c=Gt(o),p=Gt(s);p>=1<<a+pr;)h=new Ct(h&&h.array.length?[h]:[],n),
+a+=pr;var v=t._tail,l=c>p?Qt(t,s-1):p>c?new Ct([],n):v;if(v&&p>c&&o>u&&v.array.length){h=Yt(h,n);for(var y=h,d=a;d>pr;d-=pr){var m=c>>>d&lr;y=y.array[m]=Yt(y.array[m],n)}y.array[c>>>pr&lr]=v}if(o>s&&(l=l&&l.removeAfter(n,0,s)),u>=p)u-=p,s-=p,a=pr,h=null,l=l&&l.removeBefore(n,0,u);else if(u>i||c>p){for(f=0;h;){var g=u>>>a&lr;if(g!==p>>>a&lr)break;g&&(f+=(1<<a)*g),a-=pr,h=h.array[g]}h&&u>i&&(h=h.removeBefore(n,a,u-f)),h&&c>p&&(h=h.removeAfter(n,a,p-f)),f&&(u-=f,s-=f)}return t.__ownerID?(t.size=s-u,t._origin=u,t._capacity=s,t._level=a,t._root=h,t._tail=l,t.__hash=void 0,t.__altered=!0,t):Nt(u,s,a,h,l)}function Ft(t,e,r){for(var i=[],u=0,s=0;r.length>s;s++){var a=r[s],h=n(a);h.size>u&&(u=h.size),o(a)||(h=h.map(function(t){return H(t)})),i.push(h)}return u>t.size&&(t=t.setSize(u)),jt(t,e,i)}function Gt(t){return vr>t?0:t-1>>>pr<<pr}function Zt(t){return null===t||void 0===t?ee():$t(t)?t:ee().withMutations(function(e){var n=r(t);ft(n.size),n.forEach(function(t,r){return e.set(r,t)})})}function $t(t){return _t(t)&&h(t)}function te(t,e,r,n){var i=Object.create(Zt.prototype);return i.size=t?t.size:0,i._map=t,i._list=e,i.__ownerID=r,i.__hash=n,i}function ee(){return Fr||(Fr=te(zt(),Pt()))}function re(t,e,r){var n,i,o=t._map,u=t._list,s=o.get(e),a=void 0!==s;if(r===yr){if(!a)return t;u.size>=vr&&u.size>=2*o.size?(i=u.filter(function(t,e){return void 0!==t&&s!==e}),n=i.toKeyedSeq().map(function(t){return t[0]}).flip().toMap(),t.__ownerID&&(n.__ownerID=i.__ownerID=t.__ownerID)):(n=o.remove(e),i=s===u.size-1?u.pop():u.set(s,void 0))}else if(a){if(r===u.get(s)[1])return t;n=o,i=u.set(s,[e,r])}else n=o.set(e,u.size),i=u.set(u.size,[e,r]);return t.__ownerID?(t.size=n.size,t._map=n,t._list=i,t.__hash=void 0,t):te(n,i)}function ne(t,e){this._iter=t,this._useKeys=e,this.size=t.size}function ie(t){this._iter=t,this.size=t.size}function oe(t){this._iter=t,this.size=t.size}function ue(t){this._iter=t,this.size=t.size}function se(t){var e=Ee(t);return e._iter=t,e.size=t.size,e.flip=function(){return t},e.reverse=function(){var e=t.reverse.apply(this);
+return e.flip=function(){return t.reverse()},e},e.has=function(e){return t.includes(e)},e.includes=function(e){return t.has(e)},e.cacheResult=Oe,e.__iterateUncached=function(e,r){var n=this;return t.__iterate(function(t,r){return e(r,t,n)!==!1},r)},e.__iteratorUncached=function(e,r){if(e===Sr){var n=t.__iterator(e,r);return new S(function(){var t=n.next();if(!t.done){var e=t.value[0];t.value[0]=t.value[1],t.value[1]=e}return t})}return t.__iterator(e===wr?gr:wr,r)},e}function ae(t,e,r){var n=Ee(t);return n.size=t.size,n.has=function(e){return t.has(e)},n.get=function(n,i){var o=t.get(n,yr);return o===yr?i:e.call(r,o,n,t)},n.__iterateUncached=function(n,i){var o=this;return t.__iterate(function(t,i,u){return n(e.call(r,t,i,u),i,o)!==!1},i)},n.__iteratorUncached=function(n,i){var o=t.__iterator(Sr,i);return new S(function(){var i=o.next();if(i.done)return i;var u=i.value,s=u[0];return z(n,s,e.call(r,u[1],s,t),i)})},n}function he(t,e){var r=Ee(t);return r._iter=t,r.size=t.size,r.reverse=function(){return t},t.flip&&(r.flip=function(){var e=se(t);return e.reverse=function(){return t.flip()},e}),r.get=function(r,n){return t.get(e?r:-1-r,n)},r.has=function(r){return t.has(e?r:-1-r)},r.includes=function(e){return t.includes(e)},r.cacheResult=Oe,r.__iterate=function(e,r){var n=this;return t.__iterate(function(t,r){return e(t,r,n)},!r)},r.__iterator=function(e,r){return t.__iterator(e,!r)},r}function fe(t,e,r,n){var i=Ee(t);return n&&(i.has=function(n){var i=t.get(n,yr);return i!==yr&&!!e.call(r,i,n,t)},i.get=function(n,i){var o=t.get(n,yr);return o!==yr&&e.call(r,o,n,t)?o:i}),i.__iterateUncached=function(i,o){var u=this,s=0;return t.__iterate(function(t,o,a){return e.call(r,t,o,a)?(s++,i(t,n?o:s-1,u)):void 0},o),s},i.__iteratorUncached=function(i,o){var u=t.__iterator(Sr,o),s=0;return new S(function(){for(;;){var o=u.next();if(o.done)return o;var a=o.value,h=a[0],f=a[1];if(e.call(r,f,h,t))return z(i,n?h:s++,f,o)}})},i}function ce(t,e,r){var n=ct().asMutable();return t.__iterate(function(i,o){n.update(e.call(r,i,o,t),0,function(t){
+return t+1})}),n.asImmutable()}function _e(t,e,r){var n=u(t),i=(h(t)?Zt():ct()).asMutable();t.__iterate(function(o,u){i.update(e.call(r,o,u,t),function(t){return t=t||[],t.push(n?[u,o]:o),t})});var o=Me(t);return i.map(function(e){return be(t,o(e))})}function pe(t,e,r,n){var i=t.size;if(void 0!==e&&(e=0|e),void 0!==r&&(r=r===1/0?i:0|r),d(e,r,i))return t;var o=m(e,i),u=g(r,i);if(o!==o||u!==u)return pe(t.toSeq().cacheResult(),e,r,n);var s,a=u-o;a===a&&(s=0>a?0:a);var h=Ee(t);return h.size=0===s?s:t.size&&s||void 0,!n&&L(t)&&s>=0&&(h.get=function(e,r){return e=l(this,e),e>=0&&s>e?t.get(e+o,r):r}),h.__iterateUncached=function(e,r){var i=this;if(0===s)return 0;if(r)return this.cacheResult().__iterate(e,r);var u=0,a=!0,h=0;return t.__iterate(function(t,r){return a&&(a=u++<o)?void 0:(h++,e(t,n?r:h-1,i)!==!1&&h!==s)}),h},h.__iteratorUncached=function(e,r){if(0!==s&&r)return this.cacheResult().__iterator(e,r);var i=0!==s&&t.__iterator(e,r),u=0,a=0;return new S(function(){for(;u++<o;)i.next();if(++a>s)return I();var t=i.next();return n||e===wr?t:e===gr?z(e,a-1,void 0,t):z(e,a-1,t.value[1],t)})},h}function ve(t,e,r){var n=Ee(t);return n.__iterateUncached=function(n,i){var o=this;if(i)return this.cacheResult().__iterate(n,i);var u=0;return t.__iterate(function(t,i,s){return e.call(r,t,i,s)&&++u&&n(t,i,o)}),u},n.__iteratorUncached=function(n,i){var o=this;if(i)return this.cacheResult().__iterator(n,i);var u=t.__iterator(Sr,i),s=!0;return new S(function(){if(!s)return I();var t=u.next();if(t.done)return t;var i=t.value,a=i[0],h=i[1];return e.call(r,h,a,o)?n===Sr?t:z(n,a,h,t):(s=!1,I())})},n}function le(t,e,r,n){var i=Ee(t);return i.__iterateUncached=function(i,o){var u=this;if(o)return this.cacheResult().__iterate(i,o);var s=!0,a=0;return t.__iterate(function(t,o,h){return s&&(s=e.call(r,t,o,h))?void 0:(a++,i(t,n?o:a-1,u))}),a},i.__iteratorUncached=function(i,o){var u=this;if(o)return this.cacheResult().__iterator(i,o);var s=t.__iterator(Sr,o),a=!0,h=0;return new S(function(){var t,o,f;do{if(t=s.next(),t.done)return n||i===wr?t:i===gr?z(i,h++,void 0,t):z(i,h++,t.value[1],t);
+var c=t.value;o=c[0],f=c[1],a&&(a=e.call(r,f,o,u))}while(a);return i===Sr?t:z(i,o,f,t)})},i}function ye(t,e){var n=u(t),i=[t].concat(e).map(function(t){return o(t)?n&&(t=r(t)):t=n?B(t):W(Array.isArray(t)?t:[t]),t}).filter(function(t){return 0!==t.size});if(0===i.length)return t;if(1===i.length){var a=i[0];if(a===t||n&&u(a)||s(t)&&s(a))return a}var h=new j(i);return n?h=h.toKeyedSeq():s(t)||(h=h.toSetSeq()),h=h.flatten(!0),h.size=i.reduce(function(t,e){if(void 0!==t){var r=e.size;if(void 0!==r)return t+r}},0),h}function de(t,e,r){var n=Ee(t);return n.__iterateUncached=function(n,i){function u(t,h){var f=this;t.__iterate(function(t,i){return(!e||e>h)&&o(t)?u(t,h+1):n(t,r?i:s++,f)===!1&&(a=!0),!a},i)}var s=0,a=!1;return u(t,0),s},n.__iteratorUncached=function(n,i){var u=t.__iterator(n,i),s=[],a=0;return new S(function(){for(;u;){var t=u.next();if(t.done===!1){var h=t.value;if(n===Sr&&(h=h[1]),e&&!(e>s.length)||!o(h))return r?t:z(n,a++,h,t);s.push(u),u=h.__iterator(n,i)}else u=s.pop()}return I()})},n}function me(t,e,r){var n=Me(t);return t.toSeq().map(function(i,o){return n(e.call(r,i,o,t))}).flatten(!0)}function ge(t,e){var r=Ee(t);return r.size=t.size&&2*t.size-1,r.__iterateUncached=function(r,n){var i=this,o=0;return t.__iterate(function(t,n){return(!o||r(e,o++,i)!==!1)&&r(t,o++,i)!==!1},n),o},r.__iteratorUncached=function(r,n){var i,o=t.__iterator(wr,n),u=0;return new S(function(){return(!i||u%2)&&(i=o.next(),i.done)?i:u%2?z(r,u++,e):z(r,u++,i.value,i)})},r}function we(t,e,r){e||(e=xe);var n=u(t),i=0,o=t.toSeq().map(function(e,n){return[n,e,i++,r?r(e,n,t):e]}).toArray();return o.sort(function(t,r){return e(t[3],r[3])||t[2]-r[2]}).forEach(n?function(t,e){o[e].length=2}:function(t,e){o[e]=t[1]}),n?x(o):s(t)?k(o):A(o)}function Se(t,e,r){if(e||(e=xe),r){var n=t.toSeq().map(function(e,n){return[e,r(e,n,t)]}).reduce(function(t,r){return ze(e,t[1],r[1])?r:t});return n&&n[0]}return t.reduce(function(t,r){return ze(e,t,r)?r:t})}function ze(t,e,r){var n=t(r,e);return 0===n&&r!==e&&(void 0===r||null===r||r!==r)||n>0}function Ie(t,r,n){
+var i=Ee(t);return i.size=new j(n).map(function(t){return t.size}).min(),i.__iterate=function(t,e){for(var r,n=this.__iterator(wr,e),i=0;!(r=n.next()).done&&t(r.value,i++,this)!==!1;);return i},i.__iteratorUncached=function(t,i){var o=n.map(function(t){return t=e(t),D(i?t.reverse():t)}),u=0,s=!1;return new S(function(){var e;return s||(e=o.map(function(t){return t.next()}),s=e.some(function(t){return t.done})),s?I():z(t,u++,r.apply(null,e.map(function(t){return t.value})))})},i}function be(t,e){return L(t)?e:t.constructor(e)}function qe(t){if(t!==Object(t))throw new TypeError("Expected [K, V] tuple: "+t)}function De(t){return ft(t.size),v(t)}function Me(t){return u(t)?r:s(t)?n:i}function Ee(t){return Object.create((u(t)?x:s(t)?k:A).prototype)}function Oe(){return this._iter.cacheResult?(this._iter.cacheResult(),this.size=this._iter.size,this):O.prototype.cacheResult.call(this)}function xe(t,e){return t>e?1:e>t?-1:0}function ke(t){var r=D(t);if(!r){if(!E(t))throw new TypeError("Expected iterable or array-like: "+t);r=D(e(t))}return r}function Ae(t,e){var r,n=function(o){if(o instanceof n)return o;if(!(this instanceof n))return new n(o);if(!r){r=!0;var u=Object.keys(t);Ue(i,u),i.size=u.length,i._name=e,i._keys=u,i._defaultValues=t}this._map=ct(o)},i=n.prototype=Object.create(Gr);return i.constructor=n,n}function je(t,e,r){var n=Object.create(Object.getPrototypeOf(t));return n._map=e,n.__ownerID=r,n}function Re(t){return t._name||t.constructor.name||"Record"}function Ue(t,e){try{e.forEach(Ke.bind(void 0,t))}catch(r){}}function Ke(t,e){Object.defineProperty(t,e,{get:function(){return this.get(e)},set:function(t){Z(this.__ownerID,"Cannot set on an immutable record."),this.set(e,t)}})}function Le(t){return null===t||void 0===t?Ce():Te(t)&&!h(t)?t:Ce().withMutations(function(e){var r=i(t);ft(r.size),r.forEach(function(t){return e.add(t)})})}function Te(t){return!(!t||!t[Zr])}function Be(t,e){return t.__ownerID?(t.size=e.size,t._map=e,t):e===t._map?t:0===e.size?t.__empty():t.__make(e)}function We(t,e){var r=Object.create($r);
+return r.size=t?t.size:0,r._map=t,r.__ownerID=e,r}function Ce(){return tn||(tn=We(zt()))}function Je(t){return null===t||void 0===t?He():Ne(t)?t:He().withMutations(function(e){var r=i(t);ft(r.size),r.forEach(function(t){return e.add(t)})})}function Ne(t){return Te(t)&&h(t)}function Pe(t,e){var r=Object.create(en);return r.size=t?t.size:0,r._map=t,r.__ownerID=e,r}function He(){return rn||(rn=Pe(ee()))}function Ve(t){return null===t||void 0===t?Xe():Ye(t)?t:Xe().unshiftAll(t)}function Ye(t){return!(!t||!t[nn])}function Qe(t,e,r,n){var i=Object.create(on);return i.size=t,i._head=e,i.__ownerID=r,i.__hash=n,i.__altered=!1,i}function Xe(){return un||(un=Qe(0))}function Fe(t,e){var r=function(r){t.prototype[r]=e[r]};return Object.keys(e).forEach(r),Object.getOwnPropertySymbols&&Object.getOwnPropertySymbols(e).forEach(r),t}function Ge(t,e){return e}function Ze(t,e){return[e,t]}function $e(t){return function(){return!t.apply(this,arguments)}}function tr(t){return function(){return-t.apply(this,arguments)}}function er(t){return"string"==typeof t?JSON.stringify(t):t+""}function rr(){return p(arguments)}function nr(t,e){return e>t?1:t>e?-1:0}function ir(t){if(t.size===1/0)return 0;var e=h(t),r=u(t),n=e?1:0,i=t.__iterate(r?e?function(t,e){n=31*n+ur(ot(t),ot(e))|0}:function(t,e){n=n+ur(ot(t),ot(e))|0}:e?function(t){n=31*n+ot(t)|0}:function(t){n=n+ot(t)|0});return or(i,n)}function or(t,e){return e=xr(e,3432918353),e=xr(e<<15|e>>>-15,461845907),e=xr(e<<13|e>>>-13,5),e=(e+3864292196|0)^t,e=xr(e^e>>>16,2246822507),e=xr(e^e>>>13,3266489909),e=it(e^e>>>16)}function ur(t,e){return t^e+2654435769+(t<<6)+(t>>2)|0}var sr=Array.prototype.slice;t(r,e),t(n,e),t(i,e),e.isIterable=o,e.isKeyed=u,e.isIndexed=s,e.isAssociative=a,e.isOrdered=h,e.Keyed=r,e.Indexed=n,e.Set=i;var ar="@@__IMMUTABLE_ITERABLE__@@",hr="@@__IMMUTABLE_KEYED__@@",fr="@@__IMMUTABLE_INDEXED__@@",cr="@@__IMMUTABLE_ORDERED__@@",_r="delete",pr=5,vr=1<<pr,lr=vr-1,yr={},dr={value:!1},mr={value:!1},gr=0,wr=1,Sr=2,zr="function"==typeof Symbol&&Symbol.iterator,Ir="@@iterator",br=zr||Ir;
+S.prototype.toString=function(){return"[Iterator]"},S.KEYS=gr,S.VALUES=wr,S.ENTRIES=Sr,S.prototype.inspect=S.prototype.toSource=function(){return""+this},S.prototype[br]=function(){return this},t(O,e),O.of=function(){return O(arguments)},O.prototype.toSeq=function(){return this},O.prototype.toString=function(){return this.__toString("Seq {","}")},O.prototype.cacheResult=function(){return!this._cache&&this.__iterateUncached&&(this._cache=this.entrySeq().toArray(),this.size=this._cache.length),this},O.prototype.__iterate=function(t,e){return N(this,t,e,!0)},O.prototype.__iterator=function(t,e){return P(this,t,e,!0)},t(x,O),x.prototype.toKeyedSeq=function(){return this},t(k,O),k.of=function(){return k(arguments)},k.prototype.toIndexedSeq=function(){return this},k.prototype.toString=function(){return this.__toString("Seq [","]")},k.prototype.__iterate=function(t,e){return N(this,t,e,!1)},k.prototype.__iterator=function(t,e){return P(this,t,e,!1)},t(A,O),A.of=function(){return A(arguments)},A.prototype.toSetSeq=function(){return this},O.isSeq=L,O.Keyed=x,O.Set=A,O.Indexed=k;var qr="@@__IMMUTABLE_SEQ__@@";O.prototype[qr]=!0,t(j,k),j.prototype.get=function(t,e){return this.has(t)?this._array[l(this,t)]:e},j.prototype.__iterate=function(t,e){for(var r=this._array,n=r.length-1,i=0;n>=i;i++)if(t(r[e?n-i:i],i,this)===!1)return i+1;return i},j.prototype.__iterator=function(t,e){var r=this._array,n=r.length-1,i=0;return new S(function(){return i>n?I():z(t,i,r[e?n-i++:i++])})},t(R,x),R.prototype.get=function(t,e){return void 0===e||this.has(t)?this._object[t]:e},R.prototype.has=function(t){return this._object.hasOwnProperty(t)},R.prototype.__iterate=function(t,e){for(var r=this._object,n=this._keys,i=n.length-1,o=0;i>=o;o++){var u=n[e?i-o:o];if(t(r[u],u,this)===!1)return o+1}return o},R.prototype.__iterator=function(t,e){var r=this._object,n=this._keys,i=n.length-1,o=0;return new S(function(){var u=n[e?i-o:o];return o++>i?I():z(t,u,r[u])})},R.prototype[cr]=!0,t(U,k),U.prototype.__iterateUncached=function(t,e){if(e)return this.cacheResult().__iterate(t,e);
+var r=this._iterable,n=D(r),i=0;if(q(n))for(var o;!(o=n.next()).done&&t(o.value,i++,this)!==!1;);return i},U.prototype.__iteratorUncached=function(t,e){if(e)return this.cacheResult().__iterator(t,e);var r=this._iterable,n=D(r);if(!q(n))return new S(I);var i=0;return new S(function(){var e=n.next();return e.done?e:z(t,i++,e.value)})},t(K,k),K.prototype.__iterateUncached=function(t,e){if(e)return this.cacheResult().__iterate(t,e);for(var r=this._iterator,n=this._iteratorCache,i=0;n.length>i;)if(t(n[i],i++,this)===!1)return i;for(var o;!(o=r.next()).done;){var u=o.value;if(n[i]=u,t(u,i++,this)===!1)break}return i},K.prototype.__iteratorUncached=function(t,e){if(e)return this.cacheResult().__iterator(t,e);var r=this._iterator,n=this._iteratorCache,i=0;return new S(function(){if(i>=n.length){var e=r.next();if(e.done)return e;n[i]=e.value}return z(t,i,n[i++])})};var Dr;t(G,k),G.prototype.toString=function(){return 0===this.size?"Repeat []":"Repeat [ "+this._value+" "+this.size+" times ]"},G.prototype.get=function(t,e){return this.has(t)?this._value:e},G.prototype.includes=function(t){return X(this._value,t)},G.prototype.slice=function(t,e){var r=this.size;return d(t,e,r)?this:new G(this._value,g(e,r)-m(t,r))},G.prototype.reverse=function(){return this},G.prototype.indexOf=function(t){return X(this._value,t)?0:-1},G.prototype.lastIndexOf=function(t){return X(this._value,t)?this.size:-1},G.prototype.__iterate=function(t,e){for(var r=0;this.size>r;r++)if(t(this._value,r,this)===!1)return r+1;return r},G.prototype.__iterator=function(t,e){var r=this,n=0;return new S(function(){return r.size>n?z(t,n++,r._value):I()})},G.prototype.equals=function(t){return t instanceof G?X(this._value,t._value):F(t)};var Mr;t($,k),$.prototype.toString=function(){return 0===this.size?"Range []":"Range [ "+this._start+"..."+this._end+(1!==this._step?" by "+this._step:"")+" ]"},$.prototype.get=function(t,e){return this.has(t)?this._start+l(this,t)*this._step:e},$.prototype.includes=function(t){var e=(t-this._start)/this._step;return e>=0&&this.size>e&&e===Math.floor(e);
+},$.prototype.slice=function(t,e){return d(t,e,this.size)?this:(t=m(t,this.size),e=g(e,this.size),t>=e?new $(0,0):new $(this.get(t,this._end),this.get(e,this._end),this._step))},$.prototype.indexOf=function(t){var e=t-this._start;if(e%this._step===0){var r=e/this._step;if(r>=0&&this.size>r)return r}return-1},$.prototype.lastIndexOf=function(t){return this.indexOf(t)},$.prototype.__iterate=function(t,e){for(var r=this.size-1,n=this._step,i=e?this._start+r*n:this._start,o=0;r>=o;o++){if(t(i,o,this)===!1)return o+1;i+=e?-n:n}return o},$.prototype.__iterator=function(t,e){var r=this.size-1,n=this._step,i=e?this._start+r*n:this._start,o=0;return new S(function(){var u=i;return i+=e?-n:n,o>r?I():z(t,o++,u)})},$.prototype.equals=function(t){return t instanceof $?this._start===t._start&&this._end===t._end&&this._step===t._step:F(this,t)};var Er;t(tt,e),t(et,tt),t(rt,tt),t(nt,tt),tt.Keyed=et,tt.Indexed=rt,tt.Set=nt;var Or,xr="function"==typeof Math.imul&&-2===Math.imul(4294967295,2)?Math.imul:function(t,e){t=0|t,e=0|e;var r=65535&t,n=65535&e;return r*n+((t>>>16)*n+r*(e>>>16)<<16>>>0)|0},kr=Object.isExtensible,Ar=function(){try{return Object.defineProperty({},"@",{}),!0}catch(t){return!1}}(),jr="function"==typeof WeakMap;jr&&(Or=new WeakMap);var Rr=0,Ur="__immutablehash__";"function"==typeof Symbol&&(Ur=Symbol(Ur));var Kr=16,Lr=255,Tr=0,Br={};t(ct,et),ct.of=function(){var t=sr.call(arguments,0);return zt().withMutations(function(e){for(var r=0;t.length>r;r+=2){if(r+1>=t.length)throw Error("Missing value for key: "+t[r]);e.set(t[r],t[r+1])}})},ct.prototype.toString=function(){return this.__toString("Map {","}")},ct.prototype.get=function(t,e){return this._root?this._root.get(0,void 0,t,e):e},ct.prototype.set=function(t,e){return It(this,t,e)},ct.prototype.setIn=function(t,e){return this.updateIn(t,yr,function(){return e})},ct.prototype.remove=function(t){return It(this,t,yr)},ct.prototype.deleteIn=function(t){return this.updateIn(t,function(){return yr})},ct.prototype.update=function(t,e,r){return 1===arguments.length?t(this):this.updateIn([t],e,r);
+},ct.prototype.updateIn=function(t,e,r){r||(r=e,e=void 0);var n=Rt(this,ke(t),e,r);return n===yr?void 0:n},ct.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._root=null,this.__hash=void 0,this.__altered=!0,this):zt()},ct.prototype.merge=function(){return xt(this,void 0,arguments)},ct.prototype.mergeWith=function(t){var e=sr.call(arguments,1);return xt(this,t,e)},ct.prototype.mergeIn=function(t){var e=sr.call(arguments,1);return this.updateIn(t,zt(),function(t){return"function"==typeof t.merge?t.merge.apply(t,e):e[e.length-1]})},ct.prototype.mergeDeep=function(){return xt(this,kt,arguments)},ct.prototype.mergeDeepWith=function(t){var e=sr.call(arguments,1);return xt(this,At(t),e)},ct.prototype.mergeDeepIn=function(t){var e=sr.call(arguments,1);return this.updateIn(t,zt(),function(t){return"function"==typeof t.mergeDeep?t.mergeDeep.apply(t,e):e[e.length-1]})},ct.prototype.sort=function(t){return Zt(we(this,t))},ct.prototype.sortBy=function(t,e){return Zt(we(this,e,t))},ct.prototype.withMutations=function(t){var e=this.asMutable();return t(e),e.wasAltered()?e.__ensureOwner(this.__ownerID):this},ct.prototype.asMutable=function(){return this.__ownerID?this:this.__ensureOwner(new _)},ct.prototype.asImmutable=function(){return this.__ensureOwner()},ct.prototype.wasAltered=function(){return this.__altered},ct.prototype.__iterator=function(t,e){return new mt(this,t,e)},ct.prototype.__iterate=function(t,e){var r=this,n=0;return this._root&&this._root.iterate(function(e){return n++,t(e[1],e[0],r)},e),n},ct.prototype.__ensureOwner=function(t){return t===this.__ownerID?this:t?St(this.size,this._root,t,this.__hash):(this.__ownerID=t,this.__altered=!1,this)},ct.isMap=_t;var Wr="@@__IMMUTABLE_MAP__@@",Cr=ct.prototype;Cr[Wr]=!0,Cr[_r]=Cr.remove,Cr.removeIn=Cr.deleteIn,pt.prototype.get=function(t,e,r,n){for(var i=this.entries,o=0,u=i.length;u>o;o++)if(X(r,i[o][0]))return i[o][1];return n},pt.prototype.update=function(t,e,r,n,i,o,u){for(var s=i===yr,a=this.entries,h=0,f=a.length;f>h&&!X(n,a[h][0]);h++);
+var _=f>h;if(_?a[h][1]===i:s)return this;if(c(u),(s||!_)&&c(o),!s||1!==a.length){if(!_&&!s&&a.length>=Nr)return Mt(t,a,n,i);var v=t&&t===this.ownerID,l=v?a:p(a);return _?s?h===f-1?l.pop():l[h]=l.pop():l[h]=[n,i]:l.push([n,i]),v?(this.entries=l,this):new pt(t,l)}},vt.prototype.get=function(t,e,r,n){void 0===e&&(e=ot(r));var i=1<<((0===t?e:e>>>t)&lr),o=this.bitmap;return 0===(o&i)?n:this.nodes[Ut(o&i-1)].get(t+pr,e,r,n)},vt.prototype.update=function(t,e,r,n,i,o,u){void 0===r&&(r=ot(n));var s=(0===e?r:r>>>e)&lr,a=1<<s,h=this.bitmap,f=0!==(h&a);if(!f&&i===yr)return this;var c=Ut(h&a-1),_=this.nodes,p=f?_[c]:void 0,v=bt(p,t,e+pr,r,n,i,o,u);if(v===p)return this;if(!f&&v&&_.length>=Pr)return Ot(t,_,h,s,v);if(f&&!v&&2===_.length&&qt(_[1^c]))return _[1^c];if(f&&v&&1===_.length&&qt(v))return v;var l=t&&t===this.ownerID,y=f?v?h:h^a:h|a,d=f?v?Kt(_,c,v,l):Tt(_,c,l):Lt(_,c,v,l);return l?(this.bitmap=y,this.nodes=d,this):new vt(t,y,d)},lt.prototype.get=function(t,e,r,n){void 0===e&&(e=ot(r));var i=(0===t?e:e>>>t)&lr,o=this.nodes[i];return o?o.get(t+pr,e,r,n):n},lt.prototype.update=function(t,e,r,n,i,o,u){void 0===r&&(r=ot(n));var s=(0===e?r:r>>>e)&lr,a=i===yr,h=this.nodes,f=h[s];if(a&&!f)return this;var c=bt(f,t,e+pr,r,n,i,o,u);if(c===f)return this;var _=this.count;if(f){if(!c&&(_--,Hr>_))return Et(t,h,_,s)}else _++;var p=t&&t===this.ownerID,v=Kt(h,s,c,p);return p?(this.count=_,this.nodes=v,this):new lt(t,_,v)},yt.prototype.get=function(t,e,r,n){for(var i=this.entries,o=0,u=i.length;u>o;o++)if(X(r,i[o][0]))return i[o][1];return n},yt.prototype.update=function(t,e,r,n,i,o,u){void 0===r&&(r=ot(n));var s=i===yr;if(r!==this.keyHash)return s?this:(c(u),c(o),Dt(this,t,e,r,[n,i]));for(var a=this.entries,h=0,f=a.length;f>h&&!X(n,a[h][0]);h++);var _=f>h;if(_?a[h][1]===i:s)return this;if(c(u),(s||!_)&&c(o),s&&2===f)return new dt(t,this.keyHash,a[1^h]);var v=t&&t===this.ownerID,l=v?a:p(a);return _?s?h===f-1?l.pop():l[h]=l.pop():l[h]=[n,i]:l.push([n,i]),v?(this.entries=l,this):new yt(t,this.keyHash,l)},dt.prototype.get=function(t,e,r,n){return X(r,this.entry[0])?this.entry[1]:n;
+},dt.prototype.update=function(t,e,r,n,i,o,u){var s=i===yr,a=X(n,this.entry[0]);return(a?i===this.entry[1]:s)?this:(c(u),s?void c(o):a?t&&t===this.ownerID?(this.entry[1]=i,this):new dt(t,this.keyHash,[n,i]):(c(o),Dt(this,t,e,ot(n),[n,i])))},pt.prototype.iterate=yt.prototype.iterate=function(t,e){for(var r=this.entries,n=0,i=r.length-1;i>=n;n++)if(t(r[e?i-n:n])===!1)return!1},vt.prototype.iterate=lt.prototype.iterate=function(t,e){for(var r=this.nodes,n=0,i=r.length-1;i>=n;n++){var o=r[e?i-n:n];if(o&&o.iterate(t,e)===!1)return!1}},dt.prototype.iterate=function(t,e){return t(this.entry)},t(mt,S),mt.prototype.next=function(){for(var t=this._type,e=this._stack;e;){var r,n=e.node,i=e.index++;if(n.entry){if(0===i)return gt(t,n.entry)}else if(n.entries){if(r=n.entries.length-1,r>=i)return gt(t,n.entries[this._reverse?r-i:i])}else if(r=n.nodes.length-1,r>=i){var o=n.nodes[this._reverse?r-i:i];if(o){if(o.entry)return gt(t,o.entry);e=this._stack=wt(o,e)}continue}e=this._stack=this._stack.__prev}return I()};var Jr,Nr=vr/4,Pr=vr/2,Hr=vr/4;t(Bt,rt),Bt.of=function(){return this(arguments)},Bt.prototype.toString=function(){return this.__toString("List [","]")},Bt.prototype.get=function(t,e){if(t=l(this,t),t>=0&&this.size>t){t+=this._origin;var r=Qt(this,t);return r&&r.array[t&lr]}return e},Bt.prototype.set=function(t,e){return Ht(this,t,e)},Bt.prototype.remove=function(t){return this.has(t)?0===t?this.shift():t===this.size-1?this.pop():this.splice(t,1):this},Bt.prototype.insert=function(t,e){return this.splice(t,0,e)},Bt.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=this._origin=this._capacity=0,this._level=pr,this._root=this._tail=null,this.__hash=void 0,this.__altered=!0,this):Pt()},Bt.prototype.push=function(){var t=arguments,e=this.size;return this.withMutations(function(r){Xt(r,0,e+t.length);for(var n=0;t.length>n;n++)r.set(e+n,t[n])})},Bt.prototype.pop=function(){return Xt(this,0,-1)},Bt.prototype.unshift=function(){var t=arguments;return this.withMutations(function(e){Xt(e,-t.length);for(var r=0;t.length>r;r++)e.set(r,t[r]);
+})},Bt.prototype.shift=function(){return Xt(this,1)},Bt.prototype.merge=function(){return Ft(this,void 0,arguments)},Bt.prototype.mergeWith=function(t){var e=sr.call(arguments,1);return Ft(this,t,e)},Bt.prototype.mergeDeep=function(){return Ft(this,kt,arguments)},Bt.prototype.mergeDeepWith=function(t){var e=sr.call(arguments,1);return Ft(this,At(t),e)},Bt.prototype.setSize=function(t){return Xt(this,0,t)},Bt.prototype.slice=function(t,e){var r=this.size;return d(t,e,r)?this:Xt(this,m(t,r),g(e,r))},Bt.prototype.__iterator=function(t,e){var r=0,n=Jt(this,e);return new S(function(){var e=n();return e===Xr?I():z(t,r++,e)})},Bt.prototype.__iterate=function(t,e){for(var r,n=0,i=Jt(this,e);(r=i())!==Xr&&t(r,n++,this)!==!1;);return n},Bt.prototype.__ensureOwner=function(t){return t===this.__ownerID?this:t?Nt(this._origin,this._capacity,this._level,this._root,this._tail,t,this.__hash):(this.__ownerID=t,this)},Bt.isList=Wt;var Vr="@@__IMMUTABLE_LIST__@@",Yr=Bt.prototype;Yr[Vr]=!0,Yr[_r]=Yr.remove,Yr.setIn=Cr.setIn,Yr.deleteIn=Yr.removeIn=Cr.removeIn,Yr.update=Cr.update,Yr.updateIn=Cr.updateIn,Yr.mergeIn=Cr.mergeIn,Yr.mergeDeepIn=Cr.mergeDeepIn,Yr.withMutations=Cr.withMutations,Yr.asMutable=Cr.asMutable,Yr.asImmutable=Cr.asImmutable,Yr.wasAltered=Cr.wasAltered,Ct.prototype.removeBefore=function(t,e,r){if(r===e?1<<e:0===this.array.length)return this;var n=r>>>e&lr;if(n>=this.array.length)return new Ct([],t);var i,o=0===n;if(e>0){var u=this.array[n];if(i=u&&u.removeBefore(t,e-pr,r),i===u&&o)return this}if(o&&!i)return this;var s=Yt(this,t);if(!o)for(var a=0;n>a;a++)s.array[a]=void 0;return i&&(s.array[n]=i),s},Ct.prototype.removeAfter=function(t,e,r){if(r===(e?1<<e:0)||0===this.array.length)return this;var n=r-1>>>e&lr;if(n>=this.array.length)return this;var i;if(e>0){var o=this.array[n];if(i=o&&o.removeAfter(t,e-pr,r),i===o&&n===this.array.length-1)return this}var u=Yt(this,t);return u.array.splice(n+1),i&&(u.array[n]=i),u};var Qr,Xr={};t(Zt,ct),Zt.of=function(){return this(arguments)},Zt.prototype.toString=function(){return this.__toString("OrderedMap {","}");
+},Zt.prototype.get=function(t,e){var r=this._map.get(t);return void 0!==r?this._list.get(r)[1]:e},Zt.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._map.clear(),this._list.clear(),this):ee()},Zt.prototype.set=function(t,e){return re(this,t,e)},Zt.prototype.remove=function(t){return re(this,t,yr)},Zt.prototype.wasAltered=function(){return this._map.wasAltered()||this._list.wasAltered()},Zt.prototype.__iterate=function(t,e){var r=this;return this._list.__iterate(function(e){return e&&t(e[1],e[0],r)},e)},Zt.prototype.__iterator=function(t,e){return this._list.fromEntrySeq().__iterator(t,e)},Zt.prototype.__ensureOwner=function(t){if(t===this.__ownerID)return this;var e=this._map.__ensureOwner(t),r=this._list.__ensureOwner(t);return t?te(e,r,t,this.__hash):(this.__ownerID=t,this._map=e,this._list=r,this)},Zt.isOrderedMap=$t,Zt.prototype[cr]=!0,Zt.prototype[_r]=Zt.prototype.remove;var Fr;t(ne,x),ne.prototype.get=function(t,e){return this._iter.get(t,e)},ne.prototype.has=function(t){return this._iter.has(t)},ne.prototype.valueSeq=function(){return this._iter.valueSeq()},ne.prototype.reverse=function(){var t=this,e=he(this,!0);return this._useKeys||(e.valueSeq=function(){return t._iter.toSeq().reverse()}),e},ne.prototype.map=function(t,e){var r=this,n=ae(this,t,e);return this._useKeys||(n.valueSeq=function(){return r._iter.toSeq().map(t,e)}),n},ne.prototype.__iterate=function(t,e){var r,n=this;return this._iter.__iterate(this._useKeys?function(e,r){return t(e,r,n)}:(r=e?De(this):0,function(i){return t(i,e?--r:r++,n)}),e)},ne.prototype.__iterator=function(t,e){if(this._useKeys)return this._iter.__iterator(t,e);var r=this._iter.__iterator(wr,e),n=e?De(this):0;return new S(function(){var i=r.next();return i.done?i:z(t,e?--n:n++,i.value,i)})},ne.prototype[cr]=!0,t(ie,k),ie.prototype.includes=function(t){return this._iter.includes(t)},ie.prototype.__iterate=function(t,e){var r=this,n=0;return this._iter.__iterate(function(e){return t(e,n++,r)},e)},ie.prototype.__iterator=function(t,e){var r=this._iter.__iterator(wr,e),n=0;
+return new S(function(){var e=r.next();return e.done?e:z(t,n++,e.value,e)})},t(oe,A),oe.prototype.has=function(t){return this._iter.includes(t)},oe.prototype.__iterate=function(t,e){var r=this;return this._iter.__iterate(function(e){return t(e,e,r)},e)},oe.prototype.__iterator=function(t,e){var r=this._iter.__iterator(wr,e);return new S(function(){var e=r.next();return e.done?e:z(t,e.value,e.value,e)})},t(ue,x),ue.prototype.entrySeq=function(){return this._iter.toSeq()},ue.prototype.__iterate=function(t,e){var r=this;return this._iter.__iterate(function(e){if(e){qe(e);var n=o(e);return t(n?e.get(1):e[1],n?e.get(0):e[0],r)}},e)},ue.prototype.__iterator=function(t,e){var r=this._iter.__iterator(wr,e);return new S(function(){for(;;){var e=r.next();if(e.done)return e;var n=e.value;if(n){qe(n);var i=o(n);return z(t,i?n.get(0):n[0],i?n.get(1):n[1],e)}}})},ie.prototype.cacheResult=ne.prototype.cacheResult=oe.prototype.cacheResult=ue.prototype.cacheResult=Oe,t(Ae,et),Ae.prototype.toString=function(){return this.__toString(Re(this)+" {","}")},Ae.prototype.has=function(t){return this._defaultValues.hasOwnProperty(t)},Ae.prototype.get=function(t,e){if(!this.has(t))return e;var r=this._defaultValues[t];return this._map?this._map.get(t,r):r},Ae.prototype.clear=function(){if(this.__ownerID)return this._map&&this._map.clear(),this;var t=this.constructor;return t._empty||(t._empty=je(this,zt()))},Ae.prototype.set=function(t,e){if(!this.has(t))throw Error('Cannot set unknown key "'+t+'" on '+Re(this));if(this._map&&!this._map.has(t)){var r=this._defaultValues[t];if(e===r)return this}var n=this._map&&this._map.set(t,e);return this.__ownerID||n===this._map?this:je(this,n)},Ae.prototype.remove=function(t){if(!this.has(t))return this;var e=this._map&&this._map.remove(t);return this.__ownerID||e===this._map?this:je(this,e)},Ae.prototype.wasAltered=function(){return this._map.wasAltered()},Ae.prototype.__iterator=function(t,e){var n=this;return r(this._defaultValues).map(function(t,e){return n.get(e)}).__iterator(t,e)},Ae.prototype.__iterate=function(t,e){
+var n=this;return r(this._defaultValues).map(function(t,e){return n.get(e)}).__iterate(t,e)},Ae.prototype.__ensureOwner=function(t){if(t===this.__ownerID)return this;var e=this._map&&this._map.__ensureOwner(t);return t?je(this,e,t):(this.__ownerID=t,this._map=e,this)};var Gr=Ae.prototype;Gr[_r]=Gr.remove,Gr.deleteIn=Gr.removeIn=Cr.removeIn,Gr.merge=Cr.merge,Gr.mergeWith=Cr.mergeWith,Gr.mergeIn=Cr.mergeIn,Gr.mergeDeep=Cr.mergeDeep,Gr.mergeDeepWith=Cr.mergeDeepWith,Gr.mergeDeepIn=Cr.mergeDeepIn,Gr.setIn=Cr.setIn,Gr.update=Cr.update,Gr.updateIn=Cr.updateIn,Gr.withMutations=Cr.withMutations,Gr.asMutable=Cr.asMutable,Gr.asImmutable=Cr.asImmutable,t(Le,nt),Le.of=function(){return this(arguments)},Le.fromKeys=function(t){return this(r(t).keySeq())},Le.prototype.toString=function(){return this.__toString("Set {","}")},Le.prototype.has=function(t){return this._map.has(t)},Le.prototype.add=function(t){return Be(this,this._map.set(t,!0))},Le.prototype.remove=function(t){return Be(this,this._map.remove(t))},Le.prototype.clear=function(){return Be(this,this._map.clear())},Le.prototype.union=function(){var t=sr.call(arguments,0);return t=t.filter(function(t){return 0!==t.size}),0===t.length?this:0!==this.size||this.__ownerID||1!==t.length?this.withMutations(function(e){for(var r=0;t.length>r;r++)i(t[r]).forEach(function(t){return e.add(t)})}):this.constructor(t[0])},Le.prototype.intersect=function(){var t=sr.call(arguments,0);if(0===t.length)return this;t=t.map(function(t){return i(t)});var e=this;return this.withMutations(function(r){e.forEach(function(e){t.every(function(t){return t.includes(e)})||r.remove(e)})})},Le.prototype.subtract=function(){var t=sr.call(arguments,0);if(0===t.length)return this;t=t.map(function(t){return i(t)});var e=this;return this.withMutations(function(r){e.forEach(function(e){t.some(function(t){return t.includes(e)})&&r.remove(e)})})},Le.prototype.merge=function(){return this.union.apply(this,arguments)},Le.prototype.mergeWith=function(t){var e=sr.call(arguments,1);return this.union.apply(this,e)},
+Le.prototype.sort=function(t){return Je(we(this,t))},Le.prototype.sortBy=function(t,e){return Je(we(this,e,t))},Le.prototype.wasAltered=function(){return this._map.wasAltered()},Le.prototype.__iterate=function(t,e){var r=this;return this._map.__iterate(function(e,n){return t(n,n,r)},e)},Le.prototype.__iterator=function(t,e){return this._map.map(function(t,e){return e}).__iterator(t,e)},Le.prototype.__ensureOwner=function(t){if(t===this.__ownerID)return this;var e=this._map.__ensureOwner(t);return t?this.__make(e,t):(this.__ownerID=t,this._map=e,this)},Le.isSet=Te;var Zr="@@__IMMUTABLE_SET__@@",$r=Le.prototype;$r[Zr]=!0,$r[_r]=$r.remove,$r.mergeDeep=$r.merge,$r.mergeDeepWith=$r.mergeWith,$r.withMutations=Cr.withMutations,$r.asMutable=Cr.asMutable,$r.asImmutable=Cr.asImmutable,$r.__empty=Ce,$r.__make=We;var tn;t(Je,Le),Je.of=function(){return this(arguments)},Je.fromKeys=function(t){return this(r(t).keySeq())},Je.prototype.toString=function(){return this.__toString("OrderedSet {","}")},Je.isOrderedSet=Ne;var en=Je.prototype;en[cr]=!0,en.__empty=He,en.__make=Pe;var rn;t(Ve,rt),Ve.of=function(){return this(arguments)},Ve.prototype.toString=function(){return this.__toString("Stack [","]")},Ve.prototype.get=function(t,e){var r=this._head;for(t=l(this,t);r&&t--;)r=r.next;return r?r.value:e},Ve.prototype.peek=function(){return this._head&&this._head.value},Ve.prototype.push=function(){if(0===arguments.length)return this;for(var t=this.size+arguments.length,e=this._head,r=arguments.length-1;r>=0;r--)e={value:arguments[r],next:e};return this.__ownerID?(this.size=t,this._head=e,this.__hash=void 0,this.__altered=!0,this):Qe(t,e)},Ve.prototype.pushAll=function(t){if(t=n(t),0===t.size)return this;ft(t.size);var e=this.size,r=this._head;return t.reverse().forEach(function(t){e++,r={value:t,next:r}}),this.__ownerID?(this.size=e,this._head=r,this.__hash=void 0,this.__altered=!0,this):Qe(e,r)},Ve.prototype.pop=function(){return this.slice(1)},Ve.prototype.unshift=function(){return this.push.apply(this,arguments)},Ve.prototype.unshiftAll=function(t){
+return this.pushAll(t)},Ve.prototype.shift=function(){return this.pop.apply(this,arguments)},Ve.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._head=void 0,this.__hash=void 0,this.__altered=!0,this):Xe()},Ve.prototype.slice=function(t,e){if(d(t,e,this.size))return this;var r=m(t,this.size),n=g(e,this.size);if(n!==this.size)return rt.prototype.slice.call(this,t,e);for(var i=this.size-r,o=this._head;r--;)o=o.next;return this.__ownerID?(this.size=i,this._head=o,this.__hash=void 0,this.__altered=!0,this):Qe(i,o)},Ve.prototype.__ensureOwner=function(t){return t===this.__ownerID?this:t?Qe(this.size,this._head,t,this.__hash):(this.__ownerID=t,this.__altered=!1,this)},Ve.prototype.__iterate=function(t,e){if(e)return this.reverse().__iterate(t);for(var r=0,n=this._head;n&&t(n.value,r++,this)!==!1;)n=n.next;return r},Ve.prototype.__iterator=function(t,e){if(e)return this.reverse().__iterator(t);var r=0,n=this._head;return new S(function(){if(n){var e=n.value;return n=n.next,z(t,r++,e)}return I()})},Ve.isStack=Ye;var nn="@@__IMMUTABLE_STACK__@@",on=Ve.prototype;on[nn]=!0,on.withMutations=Cr.withMutations,on.asMutable=Cr.asMutable,on.asImmutable=Cr.asImmutable,on.wasAltered=Cr.wasAltered;var un;e.Iterator=S,Fe(e,{toArray:function(){ft(this.size);var t=Array(this.size||0);return this.valueSeq().__iterate(function(e,r){t[r]=e}),t},toIndexedSeq:function(){return new ie(this)},toJS:function(){return this.toSeq().map(function(t){return t&&"function"==typeof t.toJS?t.toJS():t}).__toJS()},toJSON:function(){return this.toSeq().map(function(t){return t&&"function"==typeof t.toJSON?t.toJSON():t}).__toJS()},toKeyedSeq:function(){return new ne(this,!0)},toMap:function(){return ct(this.toKeyedSeq())},toObject:function(){ft(this.size);var t={};return this.__iterate(function(e,r){t[r]=e}),t},toOrderedMap:function(){return Zt(this.toKeyedSeq())},toOrderedSet:function(){return Je(u(this)?this.valueSeq():this)},toSet:function(){return Le(u(this)?this.valueSeq():this)},toSetSeq:function(){return new oe(this);
+},toSeq:function(){return s(this)?this.toIndexedSeq():u(this)?this.toKeyedSeq():this.toSetSeq()},toStack:function(){return Ve(u(this)?this.valueSeq():this)},toList:function(){return Bt(u(this)?this.valueSeq():this)},toString:function(){return"[Iterable]"},__toString:function(t,e){return 0===this.size?t+e:t+" "+this.toSeq().map(this.__toStringMapper).join(", ")+" "+e},concat:function(){var t=sr.call(arguments,0);return be(this,ye(this,t))},includes:function(t){return this.some(function(e){return X(e,t)})},entries:function(){return this.__iterator(Sr)},every:function(t,e){ft(this.size);var r=!0;return this.__iterate(function(n,i,o){return t.call(e,n,i,o)?void 0:(r=!1,!1)}),r},filter:function(t,e){return be(this,fe(this,t,e,!0))},find:function(t,e,r){var n=this.findEntry(t,e);return n?n[1]:r},forEach:function(t,e){return ft(this.size),this.__iterate(e?t.bind(e):t)},join:function(t){ft(this.size),t=void 0!==t?""+t:",";var e="",r=!0;return this.__iterate(function(n){r?r=!1:e+=t,e+=null!==n&&void 0!==n?""+n:""}),e},keys:function(){return this.__iterator(gr)},map:function(t,e){return be(this,ae(this,t,e))},reduce:function(t,e,r){ft(this.size);var n,i;return arguments.length<2?i=!0:n=e,this.__iterate(function(e,o,u){i?(i=!1,n=e):n=t.call(r,n,e,o,u)}),n},reduceRight:function(t,e,r){var n=this.toKeyedSeq().reverse();return n.reduce.apply(n,arguments)},reverse:function(){return be(this,he(this,!0))},slice:function(t,e){return be(this,pe(this,t,e,!0))},some:function(t,e){return!this.every($e(t),e)},sort:function(t){return be(this,we(this,t))},values:function(){return this.__iterator(wr)},butLast:function(){return this.slice(0,-1)},isEmpty:function(){return void 0!==this.size?0===this.size:!this.some(function(){return!0})},count:function(t,e){return v(t?this.toSeq().filter(t,e):this)},countBy:function(t,e){return ce(this,t,e)},equals:function(t){return F(this,t)},entrySeq:function(){var t=this;if(t._cache)return new j(t._cache);var e=t.toSeq().map(Ze).toIndexedSeq();return e.fromEntrySeq=function(){return t.toSeq()},e},filterNot:function(t,e){
+return this.filter($e(t),e)},findEntry:function(t,e,r){var n=r;return this.__iterate(function(r,i,o){return t.call(e,r,i,o)?(n=[i,r],!1):void 0}),n},findKey:function(t,e){var r=this.findEntry(t,e);return r&&r[0]},findLast:function(t,e,r){return this.toKeyedSeq().reverse().find(t,e,r)},findLastEntry:function(t,e,r){return this.toKeyedSeq().reverse().findEntry(t,e,r)},findLastKey:function(t,e){return this.toKeyedSeq().reverse().findKey(t,e)},first:function(){return this.find(y)},flatMap:function(t,e){return be(this,me(this,t,e))},flatten:function(t){return be(this,de(this,t,!0))},fromEntrySeq:function(){return new ue(this)},get:function(t,e){return this.find(function(e,r){return X(r,t)},void 0,e)},getIn:function(t,e){for(var r,n=this,i=ke(t);!(r=i.next()).done;){var o=r.value;if(n=n&&n.get?n.get(o,yr):yr,n===yr)return e}return n},groupBy:function(t,e){return _e(this,t,e)},has:function(t){return this.get(t,yr)!==yr},hasIn:function(t){return this.getIn(t,yr)!==yr},isSubset:function(t){return t="function"==typeof t.includes?t:e(t),this.every(function(e){return t.includes(e)})},isSuperset:function(t){return t="function"==typeof t.isSubset?t:e(t),t.isSubset(this)},keyOf:function(t){return this.findKey(function(e){return X(e,t)})},keySeq:function(){return this.toSeq().map(Ge).toIndexedSeq()},last:function(){return this.toSeq().reverse().first()},lastKeyOf:function(t){return this.toKeyedSeq().reverse().keyOf(t)},max:function(t){return Se(this,t)},maxBy:function(t,e){return Se(this,e,t)},min:function(t){return Se(this,t?tr(t):nr)},minBy:function(t,e){return Se(this,e?tr(e):nr,t)},rest:function(){return this.slice(1)},skip:function(t){return this.slice(Math.max(0,t))},skipLast:function(t){return be(this,this.toSeq().reverse().skip(t).reverse())},skipWhile:function(t,e){return be(this,le(this,t,e,!0))},skipUntil:function(t,e){return this.skipWhile($e(t),e)},sortBy:function(t,e){return be(this,we(this,e,t))},take:function(t){return this.slice(0,Math.max(0,t))},takeLast:function(t){return be(this,this.toSeq().reverse().take(t).reverse());
+},takeWhile:function(t,e){return be(this,ve(this,t,e))},takeUntil:function(t,e){return this.takeWhile($e(t),e)},valueSeq:function(){return this.toIndexedSeq()},hashCode:function(){return this.__hash||(this.__hash=ir(this))}});var sn=e.prototype;sn[ar]=!0,sn[br]=sn.values,sn.__toJS=sn.toArray,sn.__toStringMapper=er,sn.inspect=sn.toSource=function(){return""+this},sn.chain=sn.flatMap,sn.contains=sn.includes,Fe(r,{flip:function(){return be(this,se(this))},mapEntries:function(t,e){var r=this,n=0;return be(this,this.toSeq().map(function(i,o){return t.call(e,[o,i],n++,r)}).fromEntrySeq())},mapKeys:function(t,e){var r=this;return be(this,this.toSeq().flip().map(function(n,i){return t.call(e,n,i,r)}).flip())}});var an=r.prototype;an[hr]=!0,an[br]=sn.entries,an.__toJS=sn.toObject,an.__toStringMapper=function(t,e){return JSON.stringify(e)+": "+er(t)},Fe(n,{toKeyedSeq:function(){return new ne(this,!1)},filter:function(t,e){return be(this,fe(this,t,e,!1))},findIndex:function(t,e){var r=this.findEntry(t,e);return r?r[0]:-1},indexOf:function(t){var e=this.keyOf(t);return void 0===e?-1:e},lastIndexOf:function(t){var e=this.lastKeyOf(t);return void 0===e?-1:e},reverse:function(){return be(this,he(this,!1))},slice:function(t,e){return be(this,pe(this,t,e,!1))},splice:function(t,e){var r=arguments.length;if(e=Math.max(0|e,0),0===r||2===r&&!e)return this;t=m(t,0>t?this.count():this.size);var n=this.slice(0,t);return be(this,1===r?n:n.concat(p(arguments,2),this.slice(t+e)))},findLastIndex:function(t,e){var r=this.findLastEntry(t,e);return r?r[0]:-1},first:function(){return this.get(0)},flatten:function(t){return be(this,de(this,t,!1))},get:function(t,e){return t=l(this,t),0>t||this.size===1/0||void 0!==this.size&&t>this.size?e:this.find(function(e,r){return r===t},void 0,e)},has:function(t){return t=l(this,t),t>=0&&(void 0!==this.size?this.size===1/0||this.size>t:-1!==this.indexOf(t))},interpose:function(t){return be(this,ge(this,t))},interleave:function(){var t=[this].concat(p(arguments)),e=Ie(this.toSeq(),k.of,t),r=e.flatten(!0);return e.size&&(r.size=e.size*t.length),
+be(this,r)},keySeq:function(){return $(0,this.size)},last:function(){return this.get(-1)},skipWhile:function(t,e){return be(this,le(this,t,e,!1))},zip:function(){var t=[this].concat(p(arguments));return be(this,Ie(this,rr,t))},zipWith:function(t){var e=p(arguments);return e[0]=this,be(this,Ie(this,t,e))}}),n.prototype[fr]=!0,n.prototype[cr]=!0,Fe(i,{get:function(t,e){return this.has(t)?t:e},includes:function(t){return this.has(t)},keySeq:function(){return this.valueSeq()}}),i.prototype.has=sn.includes,i.prototype.contains=i.prototype.includes,Fe(x,r.prototype),Fe(k,n.prototype),Fe(A,i.prototype),Fe(et,r.prototype),Fe(rt,n.prototype),Fe(nt,i.prototype);var hn={Iterable:e,Seq:O,Collection:tt,Map:ct,OrderedMap:Zt,List:Bt,Stack:Ve,Set:Le,OrderedSet:Je,Record:Ae,Range:$,Repeat:G,is:X,fromJS:H};return hn});

src/drf_yasg/static/drf-yasg/redoc-init.js

@@ -0,0 +1,67 @@
+"use strict";
+
+var currentPath = window.location.protocol + "//" + window.location.host + window.location.pathname;
+var specURL = currentPath + '?format=openapi';
+var redoc = document.createElement("redoc");
+
+var redocSettings = JSON.parse(document.getElementById('redoc-settings').innerHTML);
+if (redocSettings.url) {
+    specURL = redocSettings.url;
+}
+delete redocSettings.url;
+if (redocSettings.fetchSchemaWithQuery) {
+    var query = new URLSearchParams(window.location.search || '').entries();
+    var url = specURL.split('?');
+    var usp = new URLSearchParams(url[1] || '');
+    for (var it = query.next(); !it.done; it = query.next()) {
+        usp.set(it.value[0], it.value[1]);
+    }
+    url[1] = usp.toString();
+    specURL = url[1] ? url.join('?') : url[0];
+}
+delete redocSettings.fetchSchemaWithQuery;
+
+redoc.setAttribute("spec-url", specURL);
+
+function camelToKebab(str) {
+    return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+for (var p in redocSettings) {
+    if (redocSettings.hasOwnProperty(p)) {
+        if (redocSettings[p] !== null && redocSettings[p] !== undefined && redocSettings[p] !== false) {
+            redoc.setAttribute(camelToKebab(p), redocSettings[p].toString());
+        }
+    }
+}
+
+document.body.replaceChild(redoc, document.getElementById('redoc-placeholder'));
+
+function hideEmptyVersion() {
+    // 'span.api-info-version' is for redoc 1.x, 'div.api-info span' is for redoc 2-alpha
+    var apiVersion = document.querySelector('span.api-info-version') || document.querySelector('div.api-info span');
+    if (!apiVersion) {
+        console.log("WARNING: could not find API versionString element (span.api-info-version)");
+        return;
+    }
+
+    var versionString = apiVersion.innerText;
+    if (versionString) {
+        // trim spaces and surrounding ()
+        versionString = versionString.replace(/ /g, '');
+        versionString = versionString.replace(/(^\()|(\)$)/g, '');
+    }
+
+    if (!versionString) {
+        // hide version element if empty
+        apiVersion.classList.add("hidden");
+    }
+}
+
+if (document.querySelector('span.api-info-version') || document.querySelector('div.api-info span')) {
+    hideEmptyVersion();
+}
+else {
+    insertionQ('span.api-info-version').every(hideEmptyVersion);
+    insertionQ('div.api-info span').every(hideEmptyVersion);
+}

src/drf_yasg/static/drf-yasg/style.css

@@ -0,0 +1,73 @@
+html {
+    box-sizing: border-box;
+    overflow: -moz-scrollbars-vertical;
+    overflow-y: scroll;
+}
+
+*,
+*:before,
+*:after {
+    box-sizing: inherit;
+}
+
+body {
+    margin: 0;
+    padding: 0;
+}
+
+body.swagger-body {
+    background: #fafafa;
+}
+
+.hidden {
+    display: none;
+}
+
+#django-session-auth > div {
+    display: inline-block;
+}
+
+#django-session-auth .btn.authorize {
+    padding: 10px 23px;
+}
+
+#django-session-auth .btn.authorize a {
+    color: #49cc90;
+    text-decoration: none;
+}
+
+#django-session-auth .hello {
+    margin-right: 5px;
+}
+
+#django-session-auth .hello .django-session {
+    font-weight: bold;
+}
+
+.label {
+    display: inline;
+    padding: .2em .6em .3em;
+    font-weight: 700;
+    line-height: 1;
+    color: #fff;
+    text-align: center;
+    white-space: nowrap;
+    vertical-align: baseline;
+    border-radius: .25em;
+}
+
+.label-primary {
+    background-color: #337ab7;
+}
+
+.divider {
+    margin-right: 8px;
+    background: #16222c44;
+    width: 2px;
+}
+
+svg.swagger-defs {
+    position: absolute;
+    width: 0;
+    height: 0;
+}

src/drf_yasg/static/drf-yasg/swagger-ui-dist/README.md

@@ -1,22 +0,0 @@
-# Swagger UI Dist
-[![NPM version](https://badge.fury.io/js/swagger-ui-dist.svg)](http://badge.fury.io/js/swagger-ui-dist)
-
-# API
-
-This module, `swagger-ui-dist`, exposes Swagger-UI's entire dist folder as a dependency-free npm module.
-Use `swagger-ui` instead, if you'd like to have npm install dependencies for you.
-
-`SwaggerUIBundle` and `SwaggerUIStandalonePreset` can be imported:
-```javascript
-  import { SwaggerUIBundle, SwaggerUIStandalonePreset } from "swagger-ui-dist"
-```
-
-To get an absolute path to this directory for static file serving, use the exported `getAbsoluteFSPath` method:
-
-```javascript
-const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath()
-
-// then instantiate server that serves files from the swaggerUiAssetPath
-```
-
-For anything else, check the [Swagger-UI](https://github.com/swagger-api/swagger-ui) repository.

src/drf_yasg/static/drf-yasg/swagger-ui-dist/index.html

@@ -1,95 +0,0 @@
-<!-- HTML for static distribution bundle build -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Swagger UI</title>
-  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
-  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
-  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
-  <style>
-    html
-    {
-      box-sizing: border-box;
-      overflow: -moz-scrollbars-vertical;
-      overflow-y: scroll;
-    }
-    *,
-    *:before,
-    *:after
-    {
-      box-sizing: inherit;
-    }
-
-    body {
-      margin:0;
-      background: #fafafa;
-    }
-  </style>
-</head>
-
-<body>
-
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
-  <defs>
-    <symbol viewBox="0 0 20 20" id="unlocked">
-          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="locked">
-      <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="close">
-      <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="large-arrow">
-      <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 20 20" id="large-arrow-down">
-      <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
-    </symbol>
-
-
-    <symbol viewBox="0 0 24 24" id="jump-to">
-      <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
-    </symbol>
-
-    <symbol viewBox="0 0 24 24" id="expand">
-      <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
-    </symbol>
-
-  </defs>
-</svg>
-
-<div id="swagger-ui"></div>
-
-<script src="./swagger-ui-bundle.js"> </script>
-<script src="./swagger-ui-standalone-preset.js"> </script>
-<script>
-window.onload = function() {
-  
-  // Build a system
-  const ui = SwaggerUIBundle({
-    url: "http://petstore.swagger.io/v2/swagger.json",
-    dom_id: '#swagger-ui',
-    deepLinking: true,
-    presets: [
-      SwaggerUIBundle.presets.apis,
-      SwaggerUIStandalonePreset
-    ],
-    plugins: [
-      SwaggerUIBundle.plugins.DownloadUrl
-    ],
-    layout: "StandaloneLayout"
-  })
-
-  window.ui = ui
-}
-</script>
-</body>
-
-</html>

src/drf_yasg/static/drf-yasg/swagger-ui-dist/oauth2-redirect.html

@@ -45,11 +45,18 @@
                 oauth2.auth.code = qp.code;
                 oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
             } else {
+                let oauthErrorMsg
+                if (qp.error) {
+                    oauthErrorMsg = "["+qp.error+"]: " +
+                        (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
+                        (qp.error_uri ? "More info: "+qp.error_uri : "");
+                }
+
                 oauth2.errCb({
                     authId: oauth2.auth.name,
                     source: "auth",
                     level: "error",
-                    message: "Authorization failed: no accessCode received from the server"
+                    message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server"
                 });
             }
         } else {

src/drf_yasg/static/drf-yasg/swagger-ui-dist/swagger-ui.css.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"swagger-ui.css","sourceRoot":""}

src/drf_yasg/static/drf-yasg/swagger-ui-init.js

@@ -0,0 +1,385 @@
+"use strict";
+var currentPath = window.location.protocol + "//" + window.location.host + window.location.pathname;
+var defaultSpecUrl = currentPath + '?format=openapi';
+
+function slugify(text) {
+    return text.toString().toLowerCase()
+        .replace(/\s+/g, '-')           // Replace spaces with -
+        .replace(/[^\w\-]+/g, '')       // Remove all non-word chars
+        .replace(/--+/g, '-')           // Replace multiple - with single -
+        .replace(/^-+/, '')             // Trim - from start of text
+        .replace(/-+$/, '');            // Trim - from end of text
+}
+
+var KEY_AUTH = slugify(window.location.pathname) + "-drf-yasg-auth";
+
+// load the saved authorization state from localStorage; ImmutableJS is used for consistency with swagger-ui state
+var savedAuth = Immutable.fromJS({});
+
+// global SwaggerUI config object; can be changed directly or by hooking initSwaggerUiConfig
+var swaggerUiConfig = {
+    url: defaultSpecUrl,
+    dom_id: '#swagger-ui',
+    displayRequestDuration: true,
+    presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIStandalonePreset
+    ],
+    plugins: [
+        SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout",
+    filter: true,
+    requestInterceptor: function (request) {
+        var headers = request.headers || {};
+        var csrftoken = document.querySelector("[name=csrfmiddlewaretoken]");
+        if (csrftoken) {
+            headers["X-CSRFToken"] = csrftoken.value;
+        }
+
+        return request;
+    }
+};
+
+function patchSwaggerUi() {
+    if (document.querySelector('.auth-wrapper #django-session-auth')) {
+        return;
+    }
+
+    var authWrapper = document.querySelector('.auth-wrapper');
+    var authorizeButton = document.querySelector('.auth-wrapper .authorize');
+    var djangoSessionAuth = document.querySelector('#django-session-auth');
+
+    if (!djangoSessionAuth) {
+        console.log("WARNING: session auth disabled");
+        return;
+    }
+
+    djangoSessionAuth = djangoSessionAuth.cloneNode(true);
+    authWrapper.insertBefore(djangoSessionAuth, authorizeButton);
+    djangoSessionAuth.classList.remove("hidden");
+}
+
+function initSwaggerUi() {
+    if (window.ui) {
+        console.log("WARNING: skipping initSwaggerUi() because window.ui is already defined");
+        return;
+    }
+    if (document.querySelector('.auth-wrapper .authorize')) {
+        patchSwaggerUi();
+    } else {
+        insertionQ('.auth-wrapper .authorize').every(patchSwaggerUi);
+    }
+
+    var swaggerSettings = JSON.parse(document.getElementById('swagger-settings').innerHTML);
+
+    var oauth2RedirectUrl = document.getElementById('oauth2-redirect-url');
+    if (oauth2RedirectUrl) {
+        if (!('oauth2RedirectUrl' in swaggerSettings)) {
+            if (oauth2RedirectUrl) {
+                swaggerSettings['oauth2RedirectUrl'] = oauth2RedirectUrl.href;
+            }
+        }
+        oauth2RedirectUrl.parentNode.removeChild(oauth2RedirectUrl);
+    }
+
+    console.log('swaggerSettings', swaggerSettings);
+    var oauth2Config = JSON.parse(document.getElementById('oauth2-config').innerHTML);
+    console.log('oauth2Config', oauth2Config);
+
+    initSwaggerUiConfig(swaggerSettings, oauth2Config);
+    window.ui = SwaggerUIBundle(swaggerUiConfig);
+    window.ui.initOAuth(oauth2Config);
+}
+
+/**
+ * Initialize the global swaggerUiConfig with any given additional settings.
+ * @param swaggerSettings SWAGGER_SETTINGS from Django settings
+ * @param oauth2Settings OAUTH2_CONFIG from Django settings
+ */
+function initSwaggerUiConfig(swaggerSettings, oauth2Settings) {
+    var persistAuth = swaggerSettings.persistAuth;
+    var refetchWithAuth = swaggerSettings.refetchWithAuth;
+    var refetchOnLogout = swaggerSettings.refetchOnLogout;
+    var fetchSchemaWithQuery = swaggerSettings.fetchSchemaWithQuery;
+    delete swaggerSettings['persistAuth'];
+    delete swaggerSettings['refetchWithAuth'];
+    delete swaggerSettings['refetchOnLogout'];
+    delete swaggerSettings['fetchSchemaWithQuery'];
+
+    for (var p in swaggerSettings) {
+        if (swaggerSettings.hasOwnProperty(p)) {
+            swaggerUiConfig[p] = swaggerSettings[p];
+        }
+    }
+
+    var specURL = swaggerUiConfig.url;
+    if (fetchSchemaWithQuery) {
+        // only add query params from document for the first spec request
+        // this ensures we otherwise honor the spec selector box which might be manually modified
+        var query = new URLSearchParams(window.location.search || '').entries();
+        for (var it = query.next(); !it.done; it = query.next()) {
+            specURL = setQueryParam(specURL, it.value[0], it.value[1]);
+        }
+    }
+    if (persistAuth) {
+        try {
+            savedAuth = Immutable.fromJS(JSON.parse(localStorage.getItem(KEY_AUTH)) || {});
+        } catch (e) {
+            localStorage.removeItem(KEY_AUTH);
+        }
+    }
+    if (refetchWithAuth) {
+        specURL = applyAuth(savedAuth, specURL) || specURL;
+    }
+    swaggerUiConfig.url = specURL;
+
+    if (persistAuth || refetchWithAuth) {
+        var hookedAuth = false;
+
+        var oldOnComplete = swaggerUiConfig.onComplete;
+        swaggerUiConfig.onComplete = function () {
+            if (persistAuth) {
+                preauthorizeAll(savedAuth, window.ui);
+            }
+
+            if (!hookedAuth) {
+                hookAuthActions(window.ui, persistAuth, refetchWithAuth, refetchOnLogout);
+                hookedAuth = true;
+            }
+            if (oldOnComplete) {
+                oldOnComplete();
+            }
+        };
+
+        var specRequestsInFlight = {};
+        var oldRequestInterceptor = swaggerUiConfig.requestInterceptor;
+        swaggerUiConfig.requestInterceptor = function (request) {
+            var headers = request.headers || {};
+            if (request.loadSpec) {
+                var newUrl = request.url;
+                if (refetchWithAuth) {
+                    newUrl = applyAuth(savedAuth, newUrl, headers) || newUrl;
+                }
+
+                if (newUrl !== request.url) {
+                    request.url = newUrl;
+
+                    if (window.ui) {
+                        // this visually updates the spec url before the request is done, i.e. while loading
+                        window.ui.specActions.updateUrl(request.url);
+                    } else {
+                        // setTimeout is needed here because the request interceptor can be called *during*
+                        // window.ui initialization (by the SwaggerUIBundle constructor)
+                        setTimeout(function () {
+                            window.ui.specActions.updateUrl(request.url);
+                        });
+                    }
+
+                    // need to manually remember requests for spec urls because
+                    // responseInterceptor has no reference to the request...
+                    var absUrl = new URL(request.url, currentPath);
+                    specRequestsInFlight[absUrl.href] = request.url;
+                }
+            }
+
+            if (oldRequestInterceptor) {
+                request = oldRequestInterceptor(request);
+            }
+            return request;
+        };
+
+        var oldResponseInterceptor = swaggerUiConfig.responseInterceptor;
+        swaggerUiConfig.responseInterceptor = function (response) {
+            var absUrl = new URL(response.url, currentPath);
+            if (absUrl.href in specRequestsInFlight) {
+                var setToUrl = specRequestsInFlight[absUrl.href];
+                delete specRequestsInFlight[absUrl.href];
+                if (response.ok) {
+                    // need setTimeout here because swagger-ui insists to call updateUrl
+                    // with the initial request url after the response...
+                    setTimeout(function () {
+                        var currentUrl = new URL(window.ui.specSelectors.url(), currentPath);
+                        if (currentUrl.href !== absUrl.href) {
+                            window.ui.specActions.updateUrl(setToUrl);
+                        }
+                    });
+                }
+            }
+
+            if (oldResponseInterceptor) {
+                response = oldResponseInterceptor(response);
+            }
+            return response;
+        }
+    }
+}
+
+function _usp(url, fn) {
+    url = url.split('?');
+    var usp = new URLSearchParams(url[1] || '');
+    fn(usp);
+    url[1] = usp.toString();
+    return url[1] ? url.join('?') : url[0];
+}
+
+function setQueryParam(url, key, value) {
+    return _usp(url, function (usp) {
+        usp.set(key, value);
+    });
+}
+
+function removeQueryParam(url, key) {
+    return _usp(url, function (usp) {
+        usp.delete(key);
+    })
+}
+
+/**
+ * Call sui.preauthorize### for all authorizations in authorization.
+ * @param authorization authorization object {key => authScheme} saved from authActions.authorize
+ * @param sui SwaggerUI or SwaggerUIBundle instance
+ */
+function preauthorizeAll(authorization, sui) {
+    authorization.valueSeq().forEach(function (authScheme) {
+        var schemeName = authScheme.get("name"), schemeType = authScheme.getIn(["schema", "type"]);
+        if (schemeType === "basic" && schemeName) {
+            var username = authScheme.getIn(["value", "username"]);
+            var password = authScheme.getIn(["value", "password"]);
+            if (username && password) {
+                sui.preauthorizeBasic(schemeName, username, password);
+            }
+        } else if (schemeType === "apiKey" && schemeName) {
+            var key = authScheme.get("value");
+            if (key) {
+                sui.preauthorizeApiKey(schemeName, key);
+            }
+        } else {
+            // TODO: OAuth2
+        }
+    });
+}
+
+/**
+ * Manually apply auth headers from the given auth object.
+ * @param {object} authorization authorization object {key => authScheme} saved from authActions.authorize
+ * @param {string} requestUrl the request url
+ * @param {object} requestHeaders target headers, modified in place by the function
+ * @return string new request url
+ */
+function applyAuth(authorization, requestUrl, requestHeaders) {
+    authorization.valueSeq().forEach(function (authScheme) {
+        requestHeaders = requestHeaders || {};
+        var schemeName = authScheme.get("name"), schemeType = authScheme.getIn(["schema", "type"]);
+        if (schemeType === "basic" && schemeName) {
+            var username = authScheme.getIn(["value", "username"]);
+            var password = authScheme.getIn(["value", "password"]);
+            if (username && password) {
+                requestHeaders["Authorization"] = "Basic " + btoa(username + ":" + password);
+            }
+        } else if (schemeType === "apiKey" && schemeName) {
+            var _in = authScheme.getIn(["schema", "in"]), paramName = authScheme.getIn(["schema", "name"]);
+            var key = authScheme.get("value");
+            if (key && paramName) {
+                if (_in === "header") {
+                    requestHeaders[paramName] = key;
+                }
+                if (_in === "query") {
+                    if (requestUrl) {
+                        requestUrl = setQueryParam(requestUrl, paramName, key);
+                    } else {
+                        console.warn("WARNING: cannot apply apiKey query parameter via interceptor");
+                    }
+                }
+            }
+        } else {
+            // TODO: OAuth2
+        }
+    });
+
+    return requestUrl;
+}
+
+/**
+ * Remove the given authorization scheme from the url.
+ * @param {object} authorization authorization object {key => authScheme} containing schemes to deauthorize
+ * @param {string} requestUrl request url
+ * @return string new request url
+ */
+function deauthUrl(authorization, requestUrl) {
+    authorization.valueSeq().forEach(function (authScheme) {
+        var schemeType = authScheme.getIn(["schema", "type"]);
+        if (schemeType === "apiKey") {
+            var _in = authScheme.getIn(["schema", "in"]), paramName = authScheme.getIn(["schema", "name"]);
+            if (_in === "query" && requestUrl && paramName) {
+                requestUrl = removeQueryParam(requestUrl, paramName);
+            }
+        } else {
+            // TODO: OAuth2?
+        }
+    });
+    return requestUrl;
+}
+
+/**
+ * Hook the authorize and logout actions of SwaggerUI.
+ * The hooks are used to persist authorization data and trigger schema refetch.
+ * @param sui SwaggerUI or SwaggerUIBundle instance
+ * @param {boolean} persistAuth true to save auth to local storage
+ * @param {boolean} refetchWithAuth true to trigger schema fetch on login
+ * @param {boolean} refetchOnLogout true to trigger schema fetch on logout
+ */
+function hookAuthActions(sui, persistAuth, refetchWithAuth, refetchOnLogout) {
+    if (!persistAuth && !refetchWithAuth) {
+        // nothing to do
+        return;
+    }
+
+    var originalAuthorize = sui.authActions.authorize;
+    sui.authActions.authorize = function (authorization) {
+        originalAuthorize(authorization);
+        // authorization is map of scheme name to scheme object
+        // need to use ImmutableJS because schema is already an ImmutableJS object
+        var newAuths = Immutable.fromJS(authorization);
+        savedAuth = savedAuth.merge(newAuths);
+
+        if (refetchWithAuth) {
+            var url = sui.specSelectors.url();
+            url = applyAuth(savedAuth, url) || url;
+            sui.specActions.updateUrl(url);
+            sui.specActions.download();
+            sui.authActions.showDefinitions(); // hide authorize dialog
+        }
+        if (persistAuth) {
+            localStorage.setItem(KEY_AUTH, JSON.stringify(savedAuth.toJSON()));
+        }
+    };
+
+    var originalLogout = sui.authActions.logout;
+    sui.authActions.logout = function (authorization) {
+        // stash logged out methods for use with deauthUrl
+        var loggedOut = savedAuth.filter(function (val, key) {
+            return authorization.indexOf(key) !== -1;
+        }).mapEntries(function (entry) {
+            return [entry[0], entry[1].set("value", null)]
+        });
+        // remove logged out methods from savedAuth
+        savedAuth = savedAuth.filter(function (val, key) {
+            return authorization.indexOf(key) === -1;
+        });
+
+        if (refetchWithAuth) {
+            var url = sui.specSelectors.url();
+            url = deauthUrl(loggedOut, url) || url;
+            sui.specActions.updateUrl(url);
+            sui.specActions.download(url);
+            sui.authActions.showDefinitions(); // hide authorize dialog
+        }
+        if (persistAuth) {
+            localStorage.setItem(KEY_AUTH, JSON.stringify(savedAuth.toJSON()));
+        }
+        originalLogout(authorization);
+    };
+}
+
+window.addEventListener('load', initSwaggerUi);

src/drf_yasg/templates/drf-yasg/redoc-old.html

@@ -0,0 +1,18 @@
+{% load static %}
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{{ title }}</title>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/style.css' %}"/>
+</head>
+<body>
+    <script id="redoc-settings" type="application/json">{{ redoc_settings | safe }}</script>
+
+    <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/redoc-init.js' %}"> </script>
+    <script src="{% static 'drf-yasg/redoc-old/redoc.min.js' %}"></script>
+</body>
+</html>

src/drf_yasg/templates/drf-yasg/redoc.html

@@ -2,42 +2,48 @@
 <!DOCTYPE html>
 <html>
 <head>
-    <title>{{ title }}</title>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <style>
-        body {
-            margin: 0;
-            padding: 0;
-        }
-        {% if not request.version %}
-        span.api-info-version {
-            display: none;
-        }
-        {% endif %}
-    </style>
+    <title>{% block title %}{{ title }}{% endblock %}</title>
+
+    {% block extra_head %}
+        {# -- Add any extra HTML heads tags here - except scripts and styles -- #}
+    {% endblock %}
+
+    {% block favicon %}
+        {# -- Maybe replace the favicon -- #}
+        <link rel="icon" type="image/png" href="{% static 'drf-yasg/redoc/redoc-logo.png' %}"/>
+    {% endblock %}
+
+    {% block main_styles %}
+        <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/style.css' %}"/>
+    {% endblock %}
+    {% block extra_styles %}
+        {# -- Add any additional CSS scripts here -- #}
+    {% endblock %}
 </head>
 <body>
-    <script>
-        var currentPath = window.location.protocol + "//" + window.location.host + window.location.pathname;
-        var specURL = currentPath + '?format=openapi';
-        var redoc = document.createElement("redoc");
-        redoc.setAttribute("spec-url", specURL);
 
-        var redocSettings = {};
-        redocSettings = {{ redoc_settings | safe }};
-        if (redocSettings.lazyRendering) {
-            redoc.setAttribute("lazy-rendering", '');
-        }
-        if (redocSettings.pathInMiddle) {
-            redoc.setAttribute("path-in-middle-panel", '');
-        }
-        if (redocSettings.hideHostname) {
-            redoc.setAttribute("hide-hostname", '');
-        }
-        redoc.setAttribute("expand-responses", redocSettings.expandResponses);
-        document.body.appendChild(redoc);
-    </script>
-    <script src="{% static 'drf-yasg/redoc/redoc.min.js' %}"> </script>
+{% block extra_body %}
+    {# -- Add any header/body markup here (rendered BEFORE the swagger-ui/redoc element) -- #}
+{% endblock %}
+
+<div id="redoc-placeholder"></div>
+
+{% block footer %}
+    {# -- Add any footer markup here (rendered AFTER the swagger-ui/redoc element) -- #}
+{% endblock %}
+
+<script id="redoc-settings" type="application/json">{{ redoc_settings | safe }}</script>
+
+{% block main_scripts %}
+    <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/url-polyfill.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/redoc-init.js' %}"></script>
+    <script src="{% static 'drf-yasg/redoc/redoc.min.js' %}"></script>
+{% endblock %}
+{% block extra_scripts %}
+    {# -- Add any additional scripts here -- #}
+{% endblock %}
 </body>
 </html>

src/drf_yasg/templates/drf-yasg/swagger-ui.html

@@ -1,223 +1,91 @@
-<!-- HTML for static distribution bundle build -->
 {% load static %}
 <!DOCTYPE html>
-<html lang="en">
+<html>
 <head>
-    <meta charset="UTF-8">
-    <title>{{ title }}</title>
-    <link
-            href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700"
-            rel="stylesheet">
-    <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/swagger-ui-dist/swagger-ui.css' %}">
-    <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-32x32.png' %}"
-          sizes="32x32"/>
-    <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-16x16.png' %}"
-          sizes="16x16"/>
-    <style>
-        html {
-            box-sizing: border-box;
-            overflow: -moz-scrollbars-vertical;
-            overflow-y: scroll;
-        }
+    <meta charset="utf-8"/>
+    <title>{% block title %}{{ title }}{% endblock %}</title>
 
-        *,
-        *:before,
-        *:after {
-            box-sizing: inherit;
-        }
+    {% block extra_head %}
+        {# -- Add any extra HTML heads tags here - except scripts and styles -- #}
+    {% endblock %}
 
-        body {
-            margin: 0;
-            background: #fafafa;
-        }
+    {% block favicon %}
+        {# -- Maybe replace the favicon -- #}
+        <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-32x32.png' %}"/>
+    {% endblock %}
 
-        #django-session-auth {
-            margin-right: 8px;
-        }
-
-        .hidden {
-            display: none;
-        }
-
-        #django-session-auth > div {
-            display: inline-block;
-        }
-
-        #django-session-auth .btn.authorize {
-            padding: 10px 23px;
-        }
-
-        #django-session-auth .btn.authorize a {
-            color: #49cc90;
-            text-decoration: none;
-        }
-
-        #django-session-auth .hello {
-            margin-right: 5px;
-        }
-
-        #django-session-auth .hello .django-session {
-            font-weight: bold;
-        }
-
-        .label {
-            display: inline;
-            padding: .2em .6em .3em;
-            font-weight: 700;
-            line-height: 1;
-            color: #fff;
-            text-align: center;
-            white-space: nowrap;
-            vertical-align: baseline;
-            border-radius: .25em;
-        }
-
-        .label-primary {
-            background-color: #337ab7;
-        }
-
-        .divider {
-            margin-right: 8px;
-            background: #16222c44;
-            width: 2px;
-        }
-    </style>
+    {% block main_styles %}
+        <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/style.css' %}"/>
+        <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/swagger-ui-dist/swagger-ui.css' %}">
+    {% endblock %}
+    {% block extra_styles %}
+        {# -- Add any additional CSS scripts here -- #}
+    {% endblock %}
 </head>
 
-<body>
+<body class="swagger-body">
 
-<svg xmlns="http://www.w3.org/2000/svg" style="position:absolute;width:0;height:0">
-    <defs>
-        <symbol viewBox="0 0 20 20" id="unlocked">
-            <path
-                    d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
-        </symbol>
-
-        <symbol viewBox="0 0 20 20" id="locked">
-            <path
-                    d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"></path>
-        </symbol>
-
-        <symbol viewBox="0 0 20 20" id="close">
-            <path
-                    d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"></path>
-        </symbol>
-
-        <symbol viewBox="0 0 20 20" id="large-arrow">
-            <path
-                    d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"></path>
-        </symbol>
-
-        <symbol viewBox="0 0 20 20" id="large-arrow-down">
-            <path
-                    d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"></path>
-        </symbol>
-
-
-        <symbol viewBox="0 0 24 24" id="jump-to">
-            <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"></path>
-        </symbol>
-
-        <symbol viewBox="0 0 24 24" id="expand">
-            <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"></path>
-        </symbol>
-
-    </defs>
-</svg>
+{% block extra_body %}
+    {# -- Add any header/body markup here (rendered BEFORE the swagger-ui/redoc element) -- #}
+{% endblock %}
 
 <div id="swagger-ui"></div>
-<div id="spec-error" class="hidden alert alert-danger"></div>
 
-<script>
-    "use strict";
-    var currentPath = window.location.protocol + "//" + window.location.host + window.location.pathname;
-    var specURL = currentPath + '?format=openapi';
+{% block footer %}
+    {# -- Add any footer markup here (rendered AFTER the swagger-ui/redoc element) -- #}
+{% endblock %}
 
-    function patchSwaggerUi() {
-        var authWrapper = document.querySelector('.auth-wrapper');
-        var authorizeButton = document.querySelector('.auth-wrapper .authorize');
-        var djangoSessionAuth = document.querySelector('#django-session-auth');
-        if (document.querySelector('.auth-wrapper #django-session-auth')) {
-            console.log("session auth already patched");
-            return;
-        }
+<script id="swagger-settings" type="application/json">{{ swagger_settings | safe }}</script>
+<script id="oauth2-config" type="application/json">{{ oauth2_config | safe }}</script>
 
-        authWrapper.insertBefore(djangoSessionAuth, authorizeButton);
-        djangoSessionAuth.classList.remove("hidden");
+{% block main_scripts %}
+    <script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-bundle.js' %}"></script>
+    <script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-standalone-preset.js' %}"></script>
+    <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/immutable.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/url-polyfill.min.js' %}"></script>
+    <script src="{% static 'drf-yasg/swagger-ui-init.js' %}"></script>
+{% endblock %}
+{% block extra_scripts %}
+    {# -- Add any additional scripts here -- #}
+{% endblock %}
 
-        var divider = document.createElement("div");
-        divider.classList.add("divider");
-        authWrapper.insertBefore(divider, authorizeButton);
-    }
+<a id="oauth2-redirect-url" href="{% static 'drf-yasg/swagger-ui-dist/oauth2-redirect.html' %}" class="hidden"></a>
 
-    function initSwaggerUi() {
-        var swaggerConfig = {
-            url: specURL,
-            dom_id: '#swagger-ui',
-            displayOperationId: true,
-            displayRequestDuration: true,
-            presets: [
-                SwaggerUIBundle.presets.apis,
-                SwaggerUIStandalonePreset
-            ],
-            plugins: [
-                SwaggerUIBundle.plugins.DownloadUrl
-            ],
-            layout: "StandaloneLayout",
-            filter: true,
-            requestInterceptor: function(request) {
-                console.log(request);
-                var headers = request.headers || {};
-                headers["X-CSRFToken"] = document.querySelector("[name=csrfmiddlewaretoken]").value;
-                return request;
-            }
-        };
+{% if USE_SESSION_AUTH %}
+    <div id="django-session-auth" class="hidden">
+        {% block session_auth_button %}
+            {% csrf_token %}
 
-        var swaggerSettings = {};
-        swaggerSettings = {{ swagger_settings | safe }};
-        console.log(swaggerSettings);
-        for (var p in swaggerSettings) {
-            if (swaggerSettings.hasOwnProperty(p)) {
-                swaggerConfig[p] = swaggerSettings[p];
-            }
-        }
-        window.ui = SwaggerUIBundle(swaggerConfig);
-    }
+            {% block user_context_message %}
+                {% if request.user.is_authenticated %}
+                    <div class="hello">
+                        <span class="django-session">Django</span> <span
+                            class="label label-primary">{{ request.user }}</span>
+                    </div>
+                {% endif %}
+            {% endblock %}
 
-    window.onload = function () {
-        insertionQ('.auth-wrapper .authorize').every(patchSwaggerUi);
-        initSwaggerUi();
-    };
-</script>
-
-<script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-bundle.js' %}"></script>
-<script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-standalone-preset.js' %}"></script>
-<script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
-
-<div id="django-session-auth" class="hidden">
-    {% if USE_SESSION_AUTH %}
-        {% csrf_token %}
-        {% if request.user.is_authenticated %}
-            <div class="hello">
-                <span class="django-session">Django</span> <span class="label label-primary">{{ request.user }}</span>
-            </div>
-        {% endif %}
-
-        {% if request.user.is_authenticated %}
-            <div class='btn authorize'>
-                <a id="auth" class="header__btn" href="{{ LOGOUT_URL }}?next={{ request.path }}" data-sw-translate>
-                    Django Logout
-                </a>
-            </div>
-        {% else %}
-            <div class='btn authorize'>
-                <a id="auth" class="header__btn" href="{{ LOGIN_URL }}?next={{ request.path }}" data-sw-translate>
-                    Django Login
-                </a>
-            </div>
-        {% endif %}
-    {% endif %}
-</div>
+            {% if request.user.is_authenticated %}
+                <div class='btn authorize'>
+                    <a id="auth" class="header__btn" href="{{ LOGOUT_URL }}?next={{ request.path }}" data-sw-translate>
+                        {% block django_logout_message %}
+                            Django Logout
+                        {% endblock %}
+                    </a>
+                </div>
+            {% else %}
+                <div class='btn authorize'>
+                    <a id="auth" class="header__btn" href="{{ LOGIN_URL }}?next={{ request.path }}" data-sw-translate>
+                        {% block django_login_message %}
+                            Django Login
+                        {% endblock %}
+                    </a>
+                </div>
+            {% endif %}
+        {% endblock %}
+    </div>
+{% endif %}
 </body>
 
 </html>

src/drf_yasg/utils.py

@@ -1,22 +1,211 @@
+import inspect
 import logging
+import sys
+import textwrap
 from collections import OrderedDict
+from decimal import Decimal
 
-from django.core.validators import RegexValidator
 from django.db import models
-from django.utils.encoding import force_text
-from rest_framework import serializers
-from rest_framework.mixins import RetrieveModelMixin, DestroyModelMixin, UpdateModelMixin
-from rest_framework.schemas.inspectors import get_pk_description
-from rest_framework.settings import api_settings
-from rest_framework.utils import json, encoders
+from django.utils.encoding import force_str
+from rest_framework import serializers, status
+from rest_framework.mixins import DestroyModelMixin, ListModelMixin, RetrieveModelMixin, UpdateModelMixin
+from rest_framework.parsers import FileUploadParser
+from rest_framework.request import is_form_media_type
+from rest_framework.settings import api_settings as rest_framework_settings
+from rest_framework.utils import encoders, json
+from rest_framework.views import APIView
 
-from . import openapi
-from .errors import SwaggerGenerationError
+from .app_settings import swagger_settings
 
 logger = logging.getLogger(__name__)
 
-#: used to forcibly remove the body of a request via :func:`.swagger_auto_schema`
-no_body = object()
+
+class no_body(object):
+    """Used as a sentinel value to forcibly remove the body of a request via :func:`.swagger_auto_schema`."""
+    pass
+
+
+class unset(object):
+    """Used as a sentinel value for function parameters not set by the caller where ``None`` would be a valid value."""
+    pass
+
+
+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, operation_summary=None,
+                        security=None, deprecated=None, responses=None, field_inspectors=None, filter_inspectors=None,
+                        paginator_inspectors=None, tags=None, **extra_overrides):
+    """Decorate a view method to customize the :class:`.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.
+
+    :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 drf_yasg.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, and can be set to ``None`` to prevent this operation from being generated
+    :param request_body: custom request body which will be used as the ``schema`` property of a
+        :class:`.Parameter` with ``in: 'body'``.
+
+        A Schema or SchemaRef is not valid if this request consumes form-data, because ``form`` and ``body`` parameters
+        are mutually exclusive in an :class:`.Operation`. If you need to set custom ``form`` parameters, you can use
+        the `manual_parameters` argument.
+
+        If a ``Serializer`` class or instance is given, it will be automatically converted into a :class:`.Schema`
+        used as a ``body`` :class:`.Parameter`, or into a list of ``form`` :class:`.Parameter`\\ s, as appropriate.
+    :type request_body: drf_yasg.openapi.Schema or drf_yasg.openapi.SchemaRef  or rest_framework.serializers.Serializer
+        or type[no_body]
+
+    :param rest_framework.serializers.Serializer query_serializer: if you use a ``Serializer`` to parse query
+        parameters, you can pass it here and have :class:`.Parameter` objects be generated automatically from it.
+
+        If any ``Field`` on the serializer cannot be represented as a ``query`` :class:`.Parameter`
+        (e.g. nested Serializers, file fields, ...), the schema generation will fail with an error.
+
+        Schema generation will also fail if the name of any Field on the `query_serializer` conflicts with parameters
+        generated by ``filter_backends`` or ``paginator``.
+
+    :param list[drf_yasg.openapi.Parameter] manual_parameters: a list of manual parameters to override the
+        automatically generated ones
+
+        :class:`.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.
+
+    :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 operation_summary: operation summary string
+    :param list[dict] 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 bool deprecated: deprecation status for operation
+    :param 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
+        suppressed.
+
+        * if a plain string is given as value, a :class:`.Response` with no body and that string as its description
+          will be generated
+        * if ``None`` is given as a value, the response is ignored; this is mainly useful for disabling default
+          2xx responses, i.e. ``responses={200: None, 302: 'something'}``
+        * if a :class:`.Schema`, :class:`.SchemaRef` is given, a :class:`.Response` with the schema as its body and
+          an empty description will be generated
+        * a ``Serializer`` class or instance will be converted into a :class:`.Schema` and treated as above
+        * a :class:`.Response` object will be used as-is; however if its ``schema`` attribute is a ``Serializer``,
+          it will automatically be converted into a :class:`.Schema`
+    :type responses: dict[int or str, (drf_yasg.openapi.Schema or drf_yasg.openapi.SchemaRef or
+        drf_yasg.openapi.Response or str or rest_framework.serializers.Serializer)]
+
+    :param list[type[drf_yasg.inspectors.FieldInspector]] field_inspectors: extra serializer and field inspectors; these
+        will be tried before :attr:`.ViewInspector.field_inspectors` on the :class:`.inspectors.SwaggerAutoSchema`
+    :param list[type[drf_yasg.inspectors.FilterInspector]] filter_inspectors: extra filter inspectors; these will be
+        tried before :attr:`.ViewInspector.filter_inspectors` on the :class:`.inspectors.SwaggerAutoSchema`
+    :param list[type[drf_yasg.inspectors.PaginatorInspector]] paginator_inspectors: extra paginator inspectors; these
+        will be tried before :attr:`.ViewInspector.paginator_inspectors` on the :class:`.inspectors.SwaggerAutoSchema`
+    :param list[str] tags: tags override
+    :param extra_overrides: extra values that will be saved into the ``overrides`` dict; these values will be available
+        in the handling :class:`.inspectors.SwaggerAutoSchema` instance via ``self.overrides``
+    """
+
+    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 = {
+            'request_body': request_body,
+            'query_serializer': query_serializer,
+            'manual_parameters': manual_parameters,
+            'operation_id': operation_id,
+            'operation_summary': operation_summary,
+            'deprecated': deprecated,
+            '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,
+            'tags': list(tags) if tags 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
+            return view_method
+
+        # if the method is an @action, it will have a bind_to_methods attribute, or a mapping attribute for drf>3.8
+        bind_to_methods = getattr(view_method, 'bind_to_methods', [])
+        mapping = getattr(view_method, 'mapping', {})
+        mapping_methods = [mth for mth, name in mapping.items() if name == view_method.__name__]
+        action_http_methods = bind_to_methods + mapping_methods
+
+        # if the method is actually a function based view (@api_view), it will have a 'cls' attribute
+        view_cls = getattr(view_method, 'cls', None)
+        api_view_http_methods = [m for m in getattr(view_cls, 'http_method_names', []) if hasattr(view_cls, m)]
+
+        available_http_methods = api_view_http_methods + action_http_methods
+        existing_data = getattr(view_method, '_swagger_auto_schema', {})
+
+        _methods = methods
+        if methods or method:
+            assert available_http_methods, "`method` or `methods` can only be specified on @action or @api_view views"
+            assert bool(methods) != bool(method), "specify either method or methods"
+            assert not isinstance(methods, str), "`methods` expects to receive a list of methods;" \
+                                                 " use `method` for a single argument"
+            if method:
+                _methods = [method.lower()]
+            else:
+                _methods = [mth.lower() for mth in methods]
+            assert all(mth in available_http_methods for mth in _methods), "http method not bound to view"
+            assert not any(mth in existing_data for mth in _methods), "http method defined multiple times"
+
+        if available_http_methods:
+            # action or api_view
+            assert bool(api_view_http_methods) != bool(action_http_methods), "this should never happen"
+
+            if len(available_http_methods) > 1:
+                assert _methods, \
+                    "on multi-method api_view or action, you must specify " \
+                    "swagger_auto_schema on a per-method basis using one of the `method` or `methods` arguments"
+            else:
+                # for a single-method view we assume that single method as the decorator target
+                _methods = _methods or available_http_methods
+
+            assert not any(hasattr(getattr(view_cls, mth, None), '_swagger_auto_schema') for mth in _methods), \
+                "swagger_auto_schema applied twice to method"
+            assert not any(mth in existing_data for mth in _methods), "swagger_auto_schema applied twice to method"
+            existing_data.update((mth.lower(), data) for mth in _methods)
+            view_method._swagger_auto_schema = existing_data
+        else:
+            assert not _methods, \
+                "the methods argument should only be specified when decorating an action; " \
+                "you should also ensure that you put the swagger_auto_schema decorator " \
+                "AFTER (above) the _route decorator"
+            assert not existing_data, "swagger_auto_schema applied twice to method"
+            view_method._swagger_auto_schema = data
+
+        return view_method
+
+    return decorator
+
+
+def swagger_serializer_method(serializer_or_field):
+    """
+    Decorates the method of a serializers.SerializerMethodField
+    to hint as to how Swagger should be generated for this field.
+
+    :param serializer_or_field: ``Serializer``/``Field`` class or instance
+    :return:
+    """
+
+    def decorator(serializer_method):
+        # stash the serializer for SerializerMethodFieldInspector to find
+        serializer_method._swagger_serializer = serializer_or_field
+        return serializer_method
+
+    return decorator
 
 
 def is_list_view(path, method, view):
@@ -27,19 +216,22 @@ def is_list_view(path, method, view):
     :param APIView view: target view
     :rtype: bool
     """
-    # for ViewSets, it could be the default 'list' action, or a list_route
+    # for ViewSets, it could be the default 'list' action, or an @action(detail=False)
     action = getattr(view, 'action', '')
-    method = getattr(view, action, None)
+    method = getattr(view, action, None) or method
     detail = getattr(method, 'detail', None)
     suffix = getattr(view, 'suffix', None)
     if action in ('list', 'create') or detail is False or suffix == 'List':
         return True
 
     if action in ('retrieve', 'update', 'partial_update', 'destroy') or detail is True or suffix == 'Instance':
-        # a detail_route is surely not a list route
+        # a detail action is surely not a list route
         return False
 
-    # for APIView, if it's a detail view it can't also be a list view
+    if isinstance(view, ListModelMixin):
+        return True
+
+    # for GenericAPIView, if it's a detail view it can't also be a list view
     if isinstance(view, (RetrieveModelMixin, UpdateModelMixin, DestroyModelMixin)):
         return False
 
@@ -52,431 +244,13 @@ def is_list_view(path, method, view):
     return True
 
 
-def swagger_auto_schema(method=None, methods=None, auto_schema=None, request_body=None, query_serializer=None,
-                        manual_parameters=None, operation_description=None, responses=None):
-    """Decorate a view method to customize the :class:`.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.
-
-    :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 .SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object
-    :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'``.
-
-        A Schema or SchemaRef is not valid if this request consumes form-data, because ``form`` and ``body`` parameters
-        are mutually exclusive in an :class:`.Operation`. If you need to set custom ``form`` parameters, you can use
-        the `manual_parameters` argument.
-
-        If a ``Serializer`` class or instance is given, it will be automatically converted into a :class:`.Schema`
-        used as a ``body`` :class:`.Parameter`, or into a list of  ``form`` :class:`.Parameter`\ s, as appropriate.
-
-    :param .Serializer query_serializer: if you use a ``Serializer`` to parse query parameters, you can pass it here
-        and have :class:`.Parameter` objects be generated automatically from it.
-
-        If any ``Field`` on the serializer cannot be represented as a ``query`` :class:`.Parameter`
-        (e.g. nested Serializers, file fields, ...), the schema generation will fail with an error.
-
-        Schema generation will also fail if the name of any Field on the `query_serializer` conflicts with parameters
-        generated by ``filter_backends`` or ``paginator``.
-
-    :param list[.Parameter] manual_parameters: a list of manual parameters to override the automatically generated ones
-
-        :class:`.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.
-
-    :param str operation_description: operation description override
-    :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
-        suppressed.
-
-        * if a plain string is given as value, a :class:`.Response` with no body and that string as its description
-          will be generated
-        * if a :class:`.Schema`, :class:`.SchemaRef` is given, a :class:`.Response` with the schema as its body and
-          an empty description will be generated
-        * a ``Serializer`` class or instance will be converted into a :class:`.Schema` and treated as above
-        * a :class:`.Response` object will be used as-is; however if its ``schema`` attribute is a ``Serializer``,
-          it will automatically be converted into a :class:`.Schema`
-
-    """
-
-    def decorator(view_method):
-        data = {
-            'auto_schema': auto_schema,
-            'request_body': request_body,
-            'query_serializer': query_serializer,
-            'manual_parameters': manual_parameters,
-            'operation_description': operation_description,
-            'responses': responses,
-        }
-        data = {k: v for k, v in data.items() if v is not None}
-
-        # if the method is a detail_route or list_route, it will have a bind_to_methods attribute
-        bind_to_methods = getattr(view_method, 'bind_to_methods', [])
-        # if the method is actually a function based view (@api_view), it will have a 'cls' attribute
-        view_cls = getattr(view_method, 'cls', None)
-        http_method_names = getattr(view_cls, 'http_method_names', [])
-        if bind_to_methods or http_method_names:
-            # detail_route, list_route or api_view
-            assert bool(http_method_names) != bool(bind_to_methods), "this should never happen"
-            available_methods = http_method_names + bind_to_methods
-            existing_data = getattr(view_method, 'swagger_auto_schema', {})
-
-            if http_method_names:
-                _route = "api_view"
-            else:
-                _route = "detail_route" if view_method.detail else "list_route"
-
-            _methods = methods
-            if len(available_methods) > 1:
-                assert methods or method, \
-                    "on multi-method %s, you must specify swagger_auto_schema on a per-method basis " \
-                    "using one of the `method` or `methods` arguments" % _route
-                assert bool(methods) != bool(method), "specify either method or methods"
-                assert not isinstance(methods, str), "`methods` expects to receive a list of methods;" \
-                                                     " use `method` for a single argument"
-                if method:
-                    _methods = [method.lower()]
-                else:
-                    _methods = [mth.lower() for mth in methods]
-                assert not any(mth in existing_data for mth in _methods), "method defined multiple times"
-                assert all(mth in available_methods for mth in _methods), "method not bound to %s" % _route
-
-                existing_data.update((mth.lower(), data) for mth in _methods)
-            else:
-                existing_data[available_methods[0]] = data
-            view_method.swagger_auto_schema = existing_data
-        else:
-            assert method is None and methods is None, \
-                "the methods argument should only be specified when decorating a detail_route or list_route; you " \
-                "should also ensure that you put the swagger_auto_schema decorator AFTER (above) the _route decorator"
-            view_method.swagger_auto_schema = data
-
-        return view_method
-
-    return decorator
-
-
-def get_model_field(queryset, field_name):
-    """Try to get information about a model and model field from a queryset.
-
-    :param queryset: the queryset
-    :param field_name: the target field name
-    :returns: the model and target field from the queryset as a 2-tuple; both elements can be ``None``
-    :rtype: tuple
-    """
-    model = getattr(queryset, 'model', None)
-    try:
-        model_field = model._meta.get_field(field_name)
-    except Exception:  # pragma: no cover
-        model_field = None
-
-    return model, model_field
-
-
-model_field_to_swagger_type = [
-    (models.AutoField, (openapi.TYPE_INTEGER, None)),
-    (models.BinaryField, (openapi.TYPE_STRING, openapi.FORMAT_BINARY)),
-    (models.BooleanField, (openapi.TYPE_BOOLEAN, None)),
-    (models.NullBooleanField, (openapi.TYPE_BOOLEAN, None)),
-    (models.DateTimeField, (openapi.TYPE_STRING, openapi.FORMAT_DATETIME)),
-    (models.DateField, (openapi.TYPE_STRING, openapi.FORMAT_DATE)),
-    (models.DecimalField, (openapi.TYPE_NUMBER, None)),
-    (models.DurationField, (openapi.TYPE_INTEGER, None)),
-    (models.FloatField, (openapi.TYPE_NUMBER, None)),
-    (models.IntegerField, (openapi.TYPE_INTEGER, None)),
-    (models.IPAddressField, (openapi.TYPE_STRING, openapi.FORMAT_IPV4)),
-    (models.GenericIPAddressField, (openapi.TYPE_STRING, openapi.FORMAT_IPV6)),
-    (models.SlugField, (openapi.TYPE_STRING, openapi.FORMAT_SLUG)),
-    (models.TextField, (openapi.TYPE_STRING, None)),
-    (models.TimeField, (openapi.TYPE_STRING, None)),
-    (models.UUIDField, (openapi.TYPE_STRING, openapi.FORMAT_UUID)),
-    (models.CharField, (openapi.TYPE_STRING, None)),
-]
-
-
-def inspect_model_field(model, model_field):
-    """Extract information from a django model field instance.
-
-    :param model: the django model
-    :param model_field: a field on the model
-    :return: description, type, format and pattern extracted from the model field
-    :rtype: OrderedDict
-    """
-    if model is not None and model_field is not None:
-        for model_field_class, tf in model_field_to_swagger_type:
-            if isinstance(model_field, model_field_class):
-                swagger_type, format = tf
-                break
-        else:  # pragma: no cover
-            swagger_type, format = None, None
-
-        if format is None or format == openapi.FORMAT_SLUG:
-            pattern = find_regex(model_field)
-        else:
-            pattern = None
-
-        if model_field.help_text:
-            description = force_text(model_field.help_text)
-        elif model_field.primary_key:
-            description = get_pk_description(model, model_field)
-        else:
-            description = None
+def guess_response_status(method):
+    if method == 'post':
+        return status.HTTP_201_CREATED
+    elif method == 'delete':
+        return status.HTTP_204_NO_CONTENT
     else:
-        description = None
-        swagger_type = None
-        format = None
-        pattern = None
-
-    result = OrderedDict([
-        ('description', description),
-        ('type', swagger_type or openapi.TYPE_STRING),
-        ('format', format),
-        ('pattern', pattern)
-    ])
-    # TODO: filter none
-    return result
-
-
-def serializer_field_to_swagger(field, swagger_object_type, definitions=None, **kwargs):
-    """Convert a drf Serializer or Field instance into a Swagger object.
-
-    :param rest_framework.serializers.Field field: the source field
-    :param type[openapi.SwaggerDict] swagger_object_type: should be one of Schema, Parameter, Items
-    :param .ReferenceResolver definitions: used to serialize Schemas by reference
-    :param kwargs: extra attributes for constructing the object;
-       if swagger_object_type is Parameter, ``name`` and ``in_`` should be provided
-    :return: the swagger object
-    :rtype: openapi.Parameter, openapi.Items, openapi.Schema
-    """
-    assert swagger_object_type in (openapi.Schema, openapi.Parameter, openapi.Items)
-    assert not isinstance(field, openapi.SwaggerDict), "passed field is already a SwaggerDict object"
-    title = force_text(field.label) if field.label else None
-    title = title if swagger_object_type == openapi.Schema else None  # only Schema has title
-    title = None
-    description = force_text(field.help_text) if field.help_text else None
-    description = description if swagger_object_type != openapi.Items else None  # Items has no description either
-
-    def SwaggerType(existing_object=None, **instance_kwargs):
-        if swagger_object_type == openapi.Parameter and 'required' not in instance_kwargs:
-            instance_kwargs['required'] = field.required
-        if swagger_object_type != openapi.Items and 'default' not in instance_kwargs:
-            default = getattr(field, 'default', serializers.empty)
-            if default is not serializers.empty:
-                if callable(default):
-                    try:
-                        if hasattr(default, 'set_context'):
-                            default.set_context(field)
-                        default = default()
-                    except Exception as e:  # pragma: no cover
-                        logger.warning("default for %s is callable but it raised an exception when "
-                                       "called; 'default' field will not be added to schema", field, exc_info=True)
-                        default = None
-
-                if default is not None:
-                    try:
-                        default = field.to_representation(default)
-                        # JSON roundtrip ensures that the value is valid JSON;
-                        # for example, sets get transformed into lists
-                        default = json.loads(json.dumps(default, cls=encoders.JSONEncoder))
-                    except Exception:  # pragma: no cover
-                        logger.warning("'default' on schema for %s will not be set because "
-                                       "to_representation raised an exception", field, exc_info=True)
-                        default = None
-
-                if default is not None:
-                    instance_kwargs['default'] = default
-
-        if swagger_object_type == openapi.Schema and 'read_only' not in instance_kwargs:
-            if field.read_only:
-                instance_kwargs['read_only'] = True
-        instance_kwargs.update(kwargs)
-        instance_kwargs.pop('title', None)
-        instance_kwargs.pop('description', None)
-
-        if existing_object is not None:
-            existing_object.title = title
-            existing_object.description = description
-            for attr, val in instance_kwargs.items():
-                setattr(existing_object, attr, val)
-            return existing_object
-
-        return swagger_object_type(title=title, description=description, **instance_kwargs)
-
-    # arrays in Schema have Schema elements, arrays in Parameter and Items have Items elements
-    ChildSwaggerType = openapi.Schema if swagger_object_type == openapi.Schema else openapi.Items
-
-    # ------ NESTED
-    if isinstance(field, (serializers.ListSerializer, serializers.ListField)):
-        child_schema = serializer_field_to_swagger(field.child, ChildSwaggerType, definitions)
-        return SwaggerType(
-            type=openapi.TYPE_ARRAY,
-            items=child_schema,
-        )
-    elif isinstance(field, serializers.Serializer):
-        if swagger_object_type != openapi.Schema:
-            raise SwaggerGenerationError("cannot instantiate nested serializer as " + swagger_object_type.__name__)
-        assert definitions is not None, "ReferenceResolver required when instantiating Schema"
-
-        serializer = field
-        if hasattr(serializer, '__ref_name__'):
-            ref_name = serializer.__ref_name__
-        else:
-            ref_name = type(serializer).__name__
-            if ref_name.endswith('Serializer'):
-                ref_name = ref_name[:-len('Serializer')]
-
-        def make_schema_definition():
-            properties = OrderedDict()
-            required = []
-            for key, value in serializer.fields.items():
-                properties[key] = serializer_field_to_swagger(value, ChildSwaggerType, definitions)
-                if value.required:
-                    required.append(key)
-
-            return SwaggerType(
-                type=openapi.TYPE_OBJECT,
-                properties=properties,
-                required=required or None,
-            )
-
-        if not ref_name:
-            return make_schema_definition()
-
-        definitions.setdefault(ref_name, make_schema_definition)
-        return openapi.SchemaRef(definitions, ref_name)
-    elif isinstance(field, serializers.ManyRelatedField):
-        child_schema = serializer_field_to_swagger(field.child_relation, ChildSwaggerType, definitions)
-        return SwaggerType(
-            type=openapi.TYPE_ARRAY,
-            items=child_schema,
-            unique_items=True,  # is this OK?
-        )
-    elif isinstance(field, serializers.PrimaryKeyRelatedField):
-        if field.pk_field:
-            result = serializer_field_to_swagger(field.pk_field, swagger_object_type, definitions, **kwargs)
-            return SwaggerType(existing_object=result)
-
-        attrs = {'type': openapi.TYPE_STRING}
-        try:
-            model = field.queryset.model
-            pk_field = model._meta.pk
-        except Exception:  # pragma: no cover
-            logger.warning("an exception was raised when attempting to extract the primary key related to %s; "
-                           "falling back to plain string" % field, exc_info=True)
-        else:
-            attrs.update(inspect_model_field(model, pk_field))
-
-        return SwaggerType(**attrs)
-    elif isinstance(field, serializers.HyperlinkedRelatedField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI)
-    elif isinstance(field, serializers.SlugRelatedField):
-        model, model_field = get_model_field(field.queryset, field.slug_field)
-        attrs = inspect_model_field(model, model_field)
-        return SwaggerType(**attrs)
-    elif isinstance(field, serializers.RelatedField):
-        return SwaggerType(type=openapi.TYPE_STRING)
-    # ------ CHOICES
-    elif isinstance(field, serializers.MultipleChoiceField):
-        return SwaggerType(
-            type=openapi.TYPE_ARRAY,
-            items=ChildSwaggerType(
-                type=openapi.TYPE_STRING,
-                enum=list(field.choices.keys())
-            )
-        )
-    elif isinstance(field, serializers.ChoiceField):
-        return SwaggerType(type=openapi.TYPE_STRING, enum=list(field.choices.keys()))
-    # ------ BOOL
-    elif isinstance(field, (serializers.BooleanField, serializers.NullBooleanField)):
-        return SwaggerType(type=openapi.TYPE_BOOLEAN)
-    # ------ NUMERIC
-    elif isinstance(field, (serializers.DecimalField, serializers.FloatField)):
-        # TODO: min_value max_value
-        return SwaggerType(type=openapi.TYPE_NUMBER)
-    elif isinstance(field, serializers.IntegerField):
-        # TODO: min_value max_value
-        return SwaggerType(type=openapi.TYPE_INTEGER)
-    elif isinstance(field, serializers.DurationField):
-        return SwaggerType(type=openapi.TYPE_INTEGER)
-    # ------ STRING
-    elif isinstance(field, serializers.EmailField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_EMAIL)
-    elif isinstance(field, serializers.RegexField):
-        return SwaggerType(type=openapi.TYPE_STRING, pattern=find_regex(field))
-    elif isinstance(field, serializers.SlugField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_SLUG, pattern=find_regex(field))
-    elif isinstance(field, serializers.URLField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI)
-    elif isinstance(field, serializers.IPAddressField):
-        format = {'ipv4': openapi.FORMAT_IPV4, 'ipv6': openapi.FORMAT_IPV6}.get(field.protocol, None)
-        return SwaggerType(type=openapi.TYPE_STRING, format=format)
-    elif isinstance(field, serializers.CharField):
-        # TODO: min_length max_length (for all CharField subclasses above too)
-        return SwaggerType(type=openapi.TYPE_STRING)
-    elif isinstance(field, serializers.UUIDField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_UUID)
-    # ------ DATE & TIME
-    elif isinstance(field, serializers.DateField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_DATE)
-    elif isinstance(field, serializers.DateTimeField):
-        return SwaggerType(type=openapi.TYPE_STRING, format=openapi.FORMAT_DATETIME)
-    # ------ OTHERS
-    elif isinstance(field, serializers.FileField):
-        # swagger 2.0 does not support specifics about file fields, so ImageFile gets no special treatment
-        # OpenAPI 3.0 does support it, so a future implementation could handle this better
-        err = SwaggerGenerationError("FileField is supported only in a formData Parameter or response Schema")
-        if swagger_object_type == openapi.Schema:
-            # FileField.to_representation returns URL or file name
-            result = SwaggerType(type=openapi.TYPE_STRING, read_only=True)
-            if getattr(field, 'use_url', api_settings.UPLOADED_FILES_USE_URL):
-                result.format = openapi.FORMAT_URI
-            return result
-        elif swagger_object_type == openapi.Parameter:
-            param = SwaggerType(type=openapi.TYPE_FILE)
-            if param['in'] != openapi.IN_FORM:
-                raise err  # pragma: no cover
-            return param
-        else:
-            raise err  # pragma: no cover
-    elif isinstance(field, serializers.DictField) and swagger_object_type == openapi.Schema:
-        child_schema = serializer_field_to_swagger(field.child, ChildSwaggerType, definitions)
-        return SwaggerType(
-            type=openapi.TYPE_OBJECT,
-            additional_properties=child_schema
-        )
-    elif isinstance(field, serializers.ModelField):
-        return SwaggerType(type=openapi.TYPE_STRING)
-
-    # TODO unhandled fields: TimeField HiddenField JSONField
-
-    # everything else gets string by default
-    return SwaggerType(type=openapi.TYPE_STRING)
-
-
-def find_regex(regex_field):
-    """Given a ``Field``, look for a ``RegexValidator`` and try to extract its pattern and return it as a string.
-
-    :param serializers.Field regex_field: the field instance
-    :return: the extracted pattern, or ``None``
-    :rtype: str
-    """
-    regex_validator = None
-    for validator in regex_field.validators:
-        if isinstance(validator, RegexValidator):
-            if regex_validator is not None:
-                # bail if multiple validators are found - no obvious way to choose
-                return None  # pragma: no cover
-            regex_validator = validator
-
-    # regex_validator.regex should be a compiled re object...
-    return getattr(getattr(regex_validator, 'regex', None), 'pattern', None)
+        return status.HTTP_200_OK
 
 
 def param_list_to_odict(parameters):
@@ -485,10 +259,258 @@ def param_list_to_odict(parameters):
 
     Raises an ``AssertionError`` if `parameters` contains duplicate parameters (by their name + in combination).
 
-    :param list[.Parameter] parameters: the list of parameters
+    :param list[drf_yasg.openapi.Parameter] parameters: the list of parameters
     :return: `parameters` keyed by ``(name, in_)``
-    :rtype: dict[tuple(str,str),.Parameter]
+    :rtype: dict[(str,str),drf_yasg.openapi.Parameter]
     """
     result = OrderedDict(((param.name, param.in_), param) for param in parameters)
     assert len(result) == len(parameters), "duplicate Parameters found"
     return result
+
+
+def merge_params(parameters, overrides):
+    """Merge `overrides` into `parameters`. This is the same as appending `overrides` to `parameters`, but any element
+    of `parameters` whose ``(name, in_)`` tuple collides with an element in `overrides` is replaced by it.
+
+    Raises an ``AssertionError`` if either list contains duplicate parameters.
+
+    :param list[drf_yasg.openapi.Parameter] parameters: initial parameters
+    :param list[drf_yasg.openapi.Parameter] overrides: overriding parameters
+    :return: merged list
+    :rtype: list[drf_yasg.openapi.Parameter]
+    """
+    parameters = param_list_to_odict(parameters)
+    parameters.update(param_list_to_odict(overrides))
+    return list(parameters.values())
+
+
+def filter_none(obj):
+    """Remove ``None`` values from tuples, lists or dictionaries. Return other objects as-is.
+
+    :param obj: the object
+    :return: collection with ``None`` values removed
+    """
+    if obj is None:
+        return None
+    new_obj = None
+    if isinstance(obj, dict):
+        new_obj = type(obj)((k, v) for k, v in obj.items() if k is not None and v is not None)
+    if isinstance(obj, (list, tuple)):
+        new_obj = type(obj)(v for v in obj if v is not None)
+    if new_obj is not None and len(new_obj) != len(obj):
+        return new_obj  # pragma: no cover
+    return obj
+
+
+def force_serializer_instance(serializer):
+    """Force `serializer` into a ``Serializer`` instance. If it is not a ``Serializer`` class or instance, raises
+    an assertion error.
+
+    :param serializer: serializer class or instance
+    :type serializer: serializers.BaseSerializer or type[serializers.BaseSerializer]
+    :return: serializer instance
+    :rtype: serializers.BaseSerializer
+    """
+    if inspect.isclass(serializer):
+        assert issubclass(serializer, serializers.BaseSerializer), "Serializer required, not %s" % serializer.__name__
+        return serializer()
+
+    assert isinstance(serializer, serializers.BaseSerializer), \
+        "Serializer class or instance required, not %s" % type(serializer).__name__
+    return serializer
+
+
+def get_serializer_class(serializer):
+    """Given a ``Serializer`` class or intance, return the ``Serializer`` class. If `serializer` is not a ``Serializer``
+    class or instance, raises an assertion error.
+
+    :param serializer: serializer class or instance, or ``None``
+    :return: serializer class
+    :rtype: type[serializers.BaseSerializer]
+    """
+    if serializer is None:
+        return None
+
+    if inspect.isclass(serializer):
+        assert issubclass(serializer, serializers.BaseSerializer), "Serializer required, not %s" % serializer.__name__
+        return serializer
+
+    assert isinstance(serializer, serializers.BaseSerializer), \
+        "Serializer class or instance required, not %s" % type(serializer).__name__
+    return type(serializer)
+
+
+def get_object_classes(classes_or_instances, expected_base_class=None):
+    """Given a list of instances or class objects, return the list of their classes.
+
+    :param classes_or_instances: mixed list to parse
+    :type classes_or_instances: list[type or object]
+    :param expected_base_class: if given, only subclasses or instances of this type will be returned
+    :type expected_base_class: type
+    :return: list of classes
+    :rtype: list
+    """
+    classes_or_instances = classes_or_instances or []
+    result = []
+    for obj in classes_or_instances:
+        if inspect.isclass(obj):
+            if not expected_base_class or issubclass(obj, expected_base_class):
+                result.append(obj)
+        else:
+            if not expected_base_class or isinstance(obj, expected_base_class):
+                result.append(type(obj))
+
+    return result
+
+
+def get_consumes(parser_classes):
+    """Extract ``consumes`` MIME types from a list of parser classes.
+
+    :param list parser_classes: parser classes
+    :type parser_classes: list[rest_framework.parsers.BaseParser or type[rest_framework.parsers.BaseParser]]
+    :return: MIME types for ``consumes``
+    :rtype: list[str]
+    """
+    parser_classes = get_object_classes(parser_classes)
+    parser_classes = [pc for pc in parser_classes if not issubclass(pc, FileUploadParser)]
+    media_types = [parser.media_type for parser in parser_classes or []]
+    non_form_media_types = [encoding for encoding in media_types if not is_form_media_type(encoding)]
+    # Because swagger Parameter objects don't support complex data types (nested objects, arrays),
+    # we can't use those unless we are sure the view *only* accepts form data
+    # This means that a view won't support file upload in swagger unless it explicitly
+    # sets its parser classes to include only form parsers
+    if len(non_form_media_types) == 0:
+        return media_types
+
+    # If the form accepts both form data and another type, like json (which is the default config),
+    # we will render its input as a Schema and thus it file parameters will be read-only
+    return non_form_media_types
+
+
+def get_produces(renderer_classes):
+    """Extract ``produces`` MIME types from a list of renderer classes.
+
+    :param list renderer_classes: renderer classes
+    :type renderer_classes: list[rest_framework.renderers.BaseRenderer or type[rest_framework.renderers.BaseRenderer]]
+    :return: MIME types for ``produces``
+    :rtype: list[str]
+    """
+    renderer_classes = get_object_classes(renderer_classes)
+    media_types = [renderer.media_type for renderer in renderer_classes or []]
+    media_types = [encoding for encoding in media_types
+                   if not any(excluded in encoding for excluded in swagger_settings.EXCLUDED_MEDIA_TYPES)]
+    return media_types
+
+
+def decimal_as_float(field):
+    """Returns true if ``field`` is a django-rest-framework DecimalField and its ``coerce_to_string`` attribute or the
+    ``COERCE_DECIMAL_TO_STRING`` setting is set to ``False``.
+
+    :rtype: bool
+    """
+    if isinstance(field, serializers.DecimalField) or isinstance(field, models.DecimalField):
+        return not getattr(field, 'coerce_to_string', rest_framework_settings.COERCE_DECIMAL_TO_STRING)
+    return False
+
+
+def get_serializer_ref_name(serializer):
+    """Get serializer's ref_name (or None for ModelSerializer if it is named 'NestedSerializer')
+
+    :param serializer: Serializer instance
+    :return: Serializer's ``ref_name`` or ``None`` for inline serializer
+    :rtype: str or None
+    """
+    serializer_meta = getattr(serializer, 'Meta', None)
+    serializer_name = type(serializer).__name__
+    if hasattr(serializer_meta, 'ref_name'):
+        ref_name = serializer_meta.ref_name
+    elif serializer_name == 'NestedSerializer' and isinstance(serializer, serializers.ModelSerializer):
+        logger.debug("Forcing inline output for ModelSerializer named 'NestedSerializer':\n" + str(serializer))
+        ref_name = None
+    else:
+        ref_name = serializer_name
+        if ref_name.endswith('Serializer'):
+            ref_name = ref_name[:-len('Serializer')]
+    return ref_name
+
+
+def force_real_str(s, encoding='utf-8', strings_only=False, errors='strict'):
+    """
+    Force `s` into a ``str`` instance.
+
+    Fix for https://github.com/axnsan12/drf-yasg/issues/159
+    """
+    if s is not None:
+        s = force_str(s, encoding, strings_only, errors)
+        if type(s) != str:
+            s = '' + s
+
+        # Remove common indentation to get the correct Markdown rendering
+        s = textwrap.dedent(s)
+
+    return s
+
+
+def field_value_to_representation(field, value):
+    """Convert a python value related to a field (default, choices, etc.) into its OpenAPI-compatible representation.
+
+    :param serializers.Field field: field associated with the value
+    :param object value: value
+    :return: the converted value
+    """
+    value = field.to_representation(value)
+    if isinstance(value, Decimal):
+        if decimal_as_float(field):
+            value = float(value)
+        else:
+            value = str(value)
+
+    # JSON roundtrip ensures that the value is valid JSON;
+    # for example, sets and tuples get transformed into lists
+    return json.loads(json.dumps(value, cls=encoders.JSONEncoder))
+
+
+def get_field_default(field):
+    """
+    Get the default value for a field, converted to a JSON-compatible value while properly handling callables.
+
+    :param field: field instance
+    :return: default value
+    """
+    default = getattr(field, 'default', serializers.empty)
+    if default is not serializers.empty:
+        if callable(default):
+            try:
+                if hasattr(default, 'set_context'):
+                    default.set_context(field)
+                if getattr(default, 'requires_context', False):
+                    default = default(field)
+                else:
+                    default = default()
+            except Exception:  # pragma: no cover
+                logger.warning("default for %s is callable but it raised an exception when "
+                               "called; 'default' will not be set on schema", field, exc_info=True)
+                default = serializers.empty
+
+        if default is not serializers.empty and default is not None:
+            try:
+                default = field_value_to_representation(field, default)
+            except Exception:  # pragma: no cover
+                logger.warning("'default' on schema for %s will not be set because "
+                               "to_representation raised an exception", field, exc_info=True)
+                default = serializers.empty
+
+    return default
+
+
+def dict_has_ordered_keys(obj):
+    """Check if a given object is a dict that maintains insertion order.
+
+    :param obj: the dict object to check
+    :rtype: bool
+    """
+    if sys.version_info >= (3, 7):
+        # the Python 3.7 language spec says that dict must maintain insertion order.
+        return isinstance(obj, dict)
+
+    return isinstance(obj, OrderedDict)

src/drf_yasg/views.py

@@ -1,8 +1,7 @@
 import warnings
-from functools import wraps
+from functools import WRAPPER_ASSIGNMENTS, wraps
 
 from django.utils.cache import add_never_cache_headers
-from django.utils.decorators import available_attrs
 from django.views.decorators.cache import cache_page
 from django.views.decorators.vary import vary_on_headers
 from rest_framework import exceptions
@@ -10,15 +9,17 @@ from rest_framework.response import Response
 from rest_framework.settings import api_settings
 from rest_framework.views import APIView
 
-from .generators import OpenAPISchemaGenerator
+from .app_settings import swagger_settings
 from .renderers import (
-    SwaggerJSONRenderer, SwaggerYAMLRenderer, SwaggerUIRenderer, ReDocRenderer, OpenAPIRenderer,
+    OpenAPIRenderer, ReDocOldRenderer, ReDocRenderer, SwaggerJSONRenderer, SwaggerUIRenderer, SwaggerYAMLRenderer,
+    _SpecRenderer
 )
 
 SPEC_RENDERERS = (SwaggerYAMLRenderer, SwaggerJSONRenderer, OpenAPIRenderer)
 UI_RENDERERS = {
     'swagger': (SwaggerUIRenderer, ReDocRenderer),
     'redoc': (ReDocRenderer, SwaggerUIRenderer),
+    'redoc-old': (ReDocOldRenderer, ReDocRenderer, SwaggerUIRenderer),
 }
 
 
@@ -28,7 +29,7 @@ def deferred_never_cache(view_func):
     never be cached.
     """
 
-    @wraps(view_func, assigned=available_attrs(view_func))
+    @wraps(view_func, assigned=WRAPPER_ASSIGNMENTS)
     def _wrapped_view_func(request, *args, **kwargs):
         response = view_func(request, *args, **kwargs)
 
@@ -46,29 +47,31 @@ def deferred_never_cache(view_func):
     return _wrapped_view_func
 
 
-def get_schema_view(info, url=None, patterns=None, urlconf=None, public=False, validators=None,
-                    generator_class=OpenAPISchemaGenerator,
-                    authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
-                    permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
-    """
-    Create a SchemaView class with default renderers and generators.
+def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=False, validators=None,
+                    generator_class=None, authentication_classes=None, permission_classes=None):
+    """Create a SchemaView class with default renderers and generators.
 
-    :param .Info info: Required. Swagger API Info object
-    :param str url: API base url; if left blank will be deduced from the location the view is served at
-    :param patterns: passed to SchemaGenerator
-    :param urlconf: passed to SchemaGenerator
-    :param bool public: if False, includes only endpoints the current user has access to
-    :param list validators: a list of validator names to apply; allowed values are ``flex``, ``ssv``
+    :param .Info info: information about the API; if omitted, defaults to :ref:`DEFAULT_INFO <default-swagger-settings>`
+    :param str url: same as :class:`.OpenAPISchemaGenerator`
+    :param patterns: same as :class:`.OpenAPISchemaGenerator`
+    :param urlconf: same as :class:`.OpenAPISchemaGenerator`
+    :param bool public: if False, includes only the endpoints that are accesible by the user viewing the schema
+    :param list validators: a list of validator names to apply; the only allowed value is ``ssv``, for now
     :param type generator_class: schema generator class to use; should be a subclass of :class:`.OpenAPISchemaGenerator`
     :param tuple authentication_classes: authentication classes for the schema view itself
     :param tuple permission_classes: permission classes for the schema view itself
     :return: SchemaView class
-    :rtype: type[.SchemaView]
+    :rtype: type[drf_yasg.views.SchemaView]
     """
     _public = public
-    _generator_class = generator_class
+    _generator_class = generator_class or swagger_settings.DEFAULT_GENERATOR_CLASS
     _auth_classes = authentication_classes
+    if _auth_classes is None:
+        _auth_classes = api_settings.DEFAULT_AUTHENTICATION_CLASSES
     _perm_classes = permission_classes
+    if _perm_classes is None:
+        _perm_classes = api_settings.DEFAULT_PERMISSION_CLASSES
+    info = info or swagger_settings.DEFAULT_INFO
     validators = validators or []
     _spec_renderers = tuple(renderer.with_validators(validators) for renderer in SPEC_RENDERERS)
 
@@ -82,17 +85,33 @@ def get_schema_view(info, url=None, patterns=None, urlconf=None, public=False, v
         renderer_classes = _spec_renderers
 
         def get(self, request, version='', format=None):
-            generator = self.generator_class(info, version, url, patterns, urlconf)
+            version = request.version or version or ''
+            if isinstance(request.accepted_renderer, _SpecRenderer):
+                generator = self.generator_class(info, version, url, patterns, urlconf)
+            else:
+                generator = self.generator_class(info, version, url, patterns=[])
+
             schema = generator.get_schema(request, self.public)
             if schema is None:
                 raise exceptions.PermissionDenied()  # pragma: no cover
             return Response(schema)
 
+        @classmethod
+        def apply_cache(cls, view, cache_timeout, cache_kwargs):
+            """Override this method to customize how caching is applied to the view.
+
+            Arguments described in :meth:`.as_cached_view`.
+            """
+            view = vary_on_headers('Cookie', 'Authorization')(view)
+            view = cache_page(cache_timeout, **cache_kwargs)(view)
+            view = deferred_never_cache(view)  # disable in-browser caching
+            return view
+
         @classmethod
         def as_cached_view(cls, 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/
+            See https://docs.djangoproject.com/en/dev/topics/cache/
 
             :param int cache_timeout: same as cache_page; set to 0 for no cache
             :param dict cache_kwargs: dictionary of kwargs to be passed to cache_page
@@ -102,10 +121,7 @@ def get_schema_view(info, url=None, patterns=None, urlconf=None, public=False, v
             cache_kwargs = cache_kwargs or {}
             view = cls.as_view(**initkwargs)
             if cache_timeout != 0:
-                if not public:
-                    view = vary_on_headers('Cookie', 'Authorization')(view)
-                view = cache_page(cache_timeout, **cache_kwargs)(view)
-                view = deferred_never_cache(view)  # disable in-browser caching
+                view = cls.apply_cache(view, cache_timeout, cache_kwargs)
             elif cache_kwargs:
                 warnings.warn("cache_kwargs ignored because cache_timeout is 0 (disabled)")
             return view
@@ -114,7 +130,7 @@ def get_schema_view(info, url=None, patterns=None, urlconf=None, public=False, v
         def without_ui(cls, 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/.
+            See https://docs.djangoproject.com/en/dev/topics/cache/.
 
             :param int cache_timeout: same as cache_page; set to 0 for no cache
             :param dict cache_kwargs: dictionary of kwargs to be passed to cache_page
@@ -126,7 +142,7 @@ def get_schema_view(info, url=None, patterns=None, urlconf=None, public=False, v
         def with_ui(cls, 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/.
+            See https://docs.djangoproject.com/en/dev/topics/cache/.
 
             :param str renderer: UI renderer; allowed values are ``swagger``, ``redoc``
             :param int cache_timeout: same as cache_page; set to 0 for no cache

testproj/articles/migrations/0001_initial.py

@@ -1,8 +1,9 @@
-# Generated by Django 2.0 on 2017-12-23 09:07
+# Generated by Django 2.0.1 on 2018-03-18 18:32
 
 from django.conf import settings
 from django.db import migrations, models
 import django.db.models.deletion
+import uuid
 
 
 class Migration(migrations.Migration):
@@ -23,8 +24,28 @@ class Migration(migrations.Migration):
                 ('slug', models.SlugField(blank=True, help_text='slug model help_text', unique=True)),
                 ('date_created', models.DateTimeField(auto_now_add=True)),
                 ('date_modified', models.DateTimeField(auto_now=True)),
+                ('article_type', models.PositiveSmallIntegerField(choices=[(1, 'first'), (2, 'second'), (3, 'third'), (7, 'seven'), (8, 'eight')], help_text='IntegerField declared on model with choices=(...) and exposed via ModelSerializer', null=True)),
                 ('cover', models.ImageField(blank=True, upload_to='article/original/')),
                 ('author', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='articles', to=settings.AUTH_USER_MODEL)),
             ],
         ),
+        migrations.CreateModel(
+            name='ArticleGroup',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('uuid', models.UUIDField(default=uuid.uuid4, editable=False, unique=True)),
+                ('title', models.CharField(help_text='title model help_text', max_length=255, unique=True)),
+                ('slug', models.SlugField(blank=True, help_text='slug model help_text', unique=True)),
+            ],
+        ),
+        migrations.AddField(
+            model_name='article',
+            name='group',
+            field=models.ForeignKey(blank=True, default=None, on_delete=django.db.models.deletion.PROTECT, related_name='articles_as_main', to='articles.ArticleGroup'),
+        ),
+        migrations.AddField(
+            model_name='article',
+            name='original_group',
+            field=models.ForeignKey(blank=True, default=None, on_delete=django.db.models.deletion.PROTECT, related_name='articles_as_original', to='articles.ArticleGroup'),
+        ),
     ]

testproj/articles/migrations/0002_article_read_only_nullable.py

@@ -0,0 +1,18 @@
+# Generated by Django 2.1.5 on 2019-03-02 03:51
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('articles', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='article',
+            name='read_only_nullable',
+            field=models.CharField(blank=True, max_length=20, null=True),
+        ),
+    ]

testproj/articles/models.py

@@ -1,3 +1,5 @@
+import uuid
+
 from django.db import models
 
 
@@ -8,5 +10,21 @@ class Article(models.Model):
     date_created = models.DateTimeField(auto_now_add=True)
     date_modified = models.DateTimeField(auto_now=True)
     author = models.ForeignKey('auth.User', related_name='articles', on_delete=models.CASCADE)
+    article_type = models.PositiveSmallIntegerField(
+        help_text="IntegerField declared on model with choices=(...) and exposed via ModelSerializer",
+        choices=((1, "first"), (2, "second"), (3, "third"), (7, "seven"), (8, "eight")), null=True
+    )
 
     cover = models.ImageField(upload_to='article/original/', blank=True)
+    group = models.ForeignKey('ArticleGroup', related_name='articles_as_main', blank=True, default=None,
+                              on_delete=models.PROTECT)
+    original_group = models.ForeignKey('ArticleGroup', related_name='articles_as_original', blank=True, default=None,
+                                       on_delete=models.PROTECT)
+    read_only_nullable = models.CharField(max_length=20, null=True, blank=True)
+
+
+class ArticleGroup(models.Model):
+    uuid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+
+    title = models.CharField(help_text="title model help_text", max_length=255, blank=False, unique=True)
+    slug = models.SlugField(help_text="slug model help_text", unique=True, blank=True)

testproj/articles/serializers.py

@@ -1,36 +1,45 @@
+from django.utils.translation import gettext_lazy as _
 from rest_framework import serializers
 
-from articles.models import Article
+from articles.models import Article, ArticleGroup
 
 
 class ArticleSerializer(serializers.ModelSerializer):
     references = serializers.DictField(
-        help_text="this is a really bad example",
+        help_text=_("this is a really bad example"),
         child=serializers.URLField(help_text="but i needed to test these 2 fields somehow"),
         read_only=True,
     )
     uuid = serializers.UUIDField(help_text="should articles have UUIDs?", read_only=True)
-    cover_name = serializers.FileField(use_url=False, source='cover', read_only=True)
+    cover_name = serializers.FileField(use_url=False, source='cover', required=True)
+    group = serializers.SlugRelatedField(slug_field='uuid', queryset=ArticleGroup.objects.all())
+    original_group = serializers.SlugRelatedField(slug_field='uuid', read_only=True)
 
     class Meta:
         model = Article
-        fields = ('title', 'author', 'body', 'slug', 'date_created', 'date_modified',
-                  'references', 'uuid', 'cover', 'cover_name')
-        read_only_fields = ('date_created', 'date_modified',
-                            'references', 'uuid', 'cover_name')
+        fields = ('title', 'author', 'body', 'slug', 'date_created', 'date_modified', 'read_only_nullable',
+                  'references', 'uuid', 'cover', 'cover_name', 'article_type', 'group', 'original_group', )
+        read_only_fields = ('date_created', 'date_modified', 'references', 'uuid', 'cover_name', 'read_only_nullable')
         lookup_field = 'slug'
         extra_kwargs = {
             'body': {'help_text': 'body serializer help_text'},
             'author': {
                 'default': serializers.CurrentUserDefault(),
-                'help_text': "The ID of the user that created this article; if none is provided, "
-                             "defaults to the currently logged in user."
+                'help_text': _("The ID of the user that created this article; if none is provided, "
+                               "defaults to the currently logged in user.")
             },
+            'read_only_nullable': {'allow_null': True},
         }
 
 
 class ImageUploadSerializer(serializers.Serializer):
-    what_am_i_doing = serializers.RegexField(regex=r"^69$", help_text="test")
+    image_id = serializers.UUIDField(read_only=True)
+    what_am_i_doing = serializers.RegexField(
+        regex=r"^69$",
+        help_text="test",
+        default="69",
+        allow_null=True
+    )
     image_styles = serializers.ListSerializer(
         child=serializers.ChoiceField(choices=['wide', 'tall', 'thumb', 'social']),
         help_text="Parameter with Items"

testproj/articles/views.py

@@ -3,19 +3,52 @@ import datetime
 from django.utils.decorators import method_decorator
 from django_filters.rest_framework import DjangoFilterBackend
 from rest_framework import viewsets
-from rest_framework.decorators import detail_route, list_route
 from rest_framework.filters import OrderingFilter
 from rest_framework.pagination import LimitOffsetPagination
-from rest_framework.parsers import MultiPartParser
+from rest_framework.parsers import FileUploadParser, MultiPartParser
 from rest_framework.response import Response
 
 from articles import serializers
 from articles.models import Article
-from drf_yasg.inspectors import SwaggerAutoSchema
-from drf_yasg.utils import swagger_auto_schema
+from drf_yasg import openapi
+from drf_yasg.app_settings import swagger_settings
+from drf_yasg.inspectors import CoreAPICompatInspector, FieldInspector, NotHandled, SwaggerAutoSchema
+from drf_yasg.utils import no_body, swagger_auto_schema
 
 
-class NoPagingAutoSchema(SwaggerAutoSchema):
+class DjangoFilterDescriptionInspector(CoreAPICompatInspector):
+    def get_filter_parameters(self, filter_backend):
+        if isinstance(filter_backend, DjangoFilterBackend):
+            result = super(DjangoFilterDescriptionInspector, self).get_filter_parameters(filter_backend)
+            for param in result:
+                if not param.get('description', ''):
+                    param.description = "Filter the returned list by {field_name}".format(field_name=param.name)
+
+            return result
+
+        return NotHandled
+
+
+class NoSchemaTitleInspector(FieldInspector):
+    def process_result(self, result, method_name, obj, **kwargs):
+        # remove the `title` attribute of all Schema objects
+        if isinstance(result, openapi.Schema.OR_REF):
+            # traverse any references and alter the Schema object in place
+            schema = openapi.resolve_ref(result, self.components)
+            schema.pop('title', None)
+
+            # no ``return schema`` here, because it would mean we always generate
+            # an inline `object` instead of a definition reference
+
+        # return back the same object that we got - i.e. a reference if we got a reference
+        return result
+
+
+class NoTitleAutoSchema(SwaggerAutoSchema):
+    field_inspectors = [NoSchemaTitleInspector] + swagger_settings.DEFAULT_FIELD_INSPECTORS
+
+
+class NoPagingAutoSchema(NoTitleAutoSchema):
     def should_page(self):
         return False
 
@@ -26,7 +59,8 @@ class ArticlePagination(LimitOffsetPagination):
 
 
 @method_decorator(name='list', decorator=swagger_auto_schema(
-    operation_description="description from swagger_auto_schema via method_decorator"
+    operation_description="description from swagger_auto_schema via method_decorator",
+    filter_inspectors=[DjangoFilterDescriptionInspector],
 ))
 class ArticleViewSet(viewsets.ModelViewSet):
     """
@@ -48,12 +82,19 @@ class ArticleViewSet(viewsets.ModelViewSet):
 
     pagination_class = ArticlePagination
     filter_backends = (DjangoFilterBackend, OrderingFilter)
-    filter_fields = ('title',)
+    filterset_fields = ('title',)
+    # django-filter 1.1 compatibility; was renamed to filterset_fields in 2.0
+    # TODO: remove when dropping support for Django 1.11
+    filter_fields = filterset_fields
     ordering_fields = ('date_modified', 'date_created')
     ordering = ('date_created',)
 
-    @swagger_auto_schema(auto_schema=NoPagingAutoSchema)
-    @list_route(methods=['get'])
+    swagger_schema = NoTitleAutoSchema
+
+    from rest_framework.decorators import action
+
+    @swagger_auto_schema(auto_schema=NoPagingAutoSchema, filter_inspectors=[DjangoFilterDescriptionInspector])
+    @action(detail=False, methods=['get'])
     def today(self, request):
         today_min = datetime.datetime.combine(datetime.date.today(), datetime.time.min)
         today_max = datetime.datetime.combine(datetime.date.today(), datetime.time.max)
@@ -63,18 +104,25 @@ class ArticleViewSet(viewsets.ModelViewSet):
 
     @swagger_auto_schema(method='get', operation_description="image GET description override")
     @swagger_auto_schema(method='post', request_body=serializers.ImageUploadSerializer)
-    @detail_route(methods=['get', 'post'], parser_classes=(MultiPartParser,))
+    @swagger_auto_schema(method='delete', manual_parameters=[openapi.Parameter(
+        name='delete_form_param', in_=openapi.IN_FORM,
+        type=openapi.TYPE_INTEGER,
+        description="this should not crash (form parameter on DELETE method)"
+    )])
+    @action(detail=True, methods=['get', 'post', 'delete'], parser_classes=(MultiPartParser, FileUploadParser))
     def image(self, request, slug=None):
         """
         image method docstring
         """
         pass
 
+    @swagger_auto_schema(request_body=no_body, operation_id='no_body_test')
     def update(self, request, *args, **kwargs):
         """update method docstring"""
         return super(ArticleViewSet, self).update(request, *args, **kwargs)
 
-    @swagger_auto_schema(operation_description="partial_update description override", responses={404: 'slug not found'})
+    @swagger_auto_schema(operation_description="partial_update description override", responses={404: 'slug not found'},
+                         operation_summary='partial_update summary', deprecated=True)
     def partial_update(self, request, *args, **kwargs):
         """partial_update method docstring"""
         return super(ArticleViewSet, self).partial_update(request, *args, **kwargs)

testproj/manage.py

@@ -3,13 +3,10 @@ import os
 import sys
 
 if __name__ == "__main__":
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testproj.settings")
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testproj.settings.local")
     try:
         from django.core.management import execute_from_command_line
     except ImportError:
-        # The above import may fail for some other reason. Ensure that the
-        # issue is really that Django is missing to avoid masking other
-        # exceptions on Python 2.
         try:
             import django  # noqa: F401
         except ImportError:

testproj/people/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class PeopleConfig(AppConfig):
+    name = 'people'

testproj/people/migrations/0001_initial.py

@@ -0,0 +1,30 @@
+# Generated by Django 2.0.1 on 2018-03-18 18:32
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Identity',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('firstName', models.CharField(max_length=30, null=True)),
+                ('lastName', models.CharField(max_length=30, null=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Person',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('identity', models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='person', to='people.Identity')),
+            ],
+        ),
+    ]