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

.gitignore

@@ -3,6 +3,7 @@ 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

@@ -16,7 +16,10 @@
     <content url="file://$MODULE_DIR$">
       <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" />

.idea/inspectionProfiles/Project_Default.xml

@@ -55,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" />

.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,32 +1,28 @@
 language: python
-sudo: false
 python:
-  - '2.7'
-  - '3.4'
-  - '3.5'
   - '3.6'
+  - '3.7'
+  - '3.8'
+
+dist: xenial
 
 cache: pip
 
-jobs:
+matrix:
   include:
-    - # workaround for python 3.7 on travis https://github.com/travis-ci/travis-ci/issues/9815#issuecomment-401756442
-      stage: test
-      python: '3.7'
-      dist: xenial
-      sudo: required
-    -
-      python: '3.6'
-      env: TOXENV=djmaster
-    - # readthedocs uses python 3.5 for building
-      python: '3.5'
+    - python: '3.6'
       env: TOXENV=docs
-    -
-      python: '3.6'
+    - 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
@@ -45,6 +41,7 @@ jobs:
   fast_finish: true
 
 install:
+  - python -m pip install -U pip setuptools
   - pip install -r requirements/ci.txt
 
 before_script:
@@ -56,22 +53,16 @@ script:
 after_success:
   - |
     if [[ -z "$TOXENV" && -z "$PYPI_DEPLOY" ]]; then
-      chmod +x coverage.sh
-      ./coverage.sh
+      coverage combine || true
+      coverage report
+      codecov
     fi
 
-branches:
-  only:
-    - master
-    - /^release\/.*$/
-    - /^v?\d+\.\d+(\.\d+)?(-?\S+)?$/
-
 stages:
   - test
   - name: publish
     if: tag IS present
 
-
 notifications:
   email:
     on_success: always

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
@@ -35,6 +35,7 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
       $ virtualenv venv
       $ source venv/bin/activate
+      (venv) $ python -m pip install -U pip setuptools
       (venv) $ pip install -U -e .[validation]
       (venv) $ pip install -U -r requirements/dev.txt
 
@@ -44,7 +45,6 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
       (venv) $ cd testproj
       (venv) $ python manage.py migrate
-      (venv) $ python manage.py shell -c "import createsuperuser"
       (venv) $ python manage.py runserver
       (venv) $ firefox localhost:8000/swagger/
 
@@ -57,8 +57,7 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
    .. code:: console
 
-      (venv) $ cd testproj
-      (venv) $ python manage.py generate_swagger ../tests/reference.yaml --overwrite --user admin --url http://test.local:8002/
+      (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.
@@ -67,11 +66,13 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
    .. code:: console
 
+      # install test dependencies
+      (venv) $ pip install -U -r requirements/test.txt
+      # run tests in the current environment, faster than tox
+      (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
-      # run tests in the current environment, faster than tox
-      (venv) $ pytest --cov
       # (optional) run tests for other python versions in separate environments
       (venv) $ tox
 
@@ -94,7 +95,7 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
 #. **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.4, 3.5 and 3.6, and building the docs succesfully.
+   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

LICENSE.rst

@@ -10,7 +10,7 @@ License
 BSD 3-Clause License
 ********************
 
-Copyright (c) 2018, 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

@@ -1,2 +1,2 @@
-release: python testproj/manage.py migrate && python testproj/manage.py shell -c "import createsuperuser"
+release: python testproj/manage.py migrate
 web: gunicorn --chdir testproj testproj.wsgi --log-file -

README.rst

@@ -7,13 +7,22 @@ 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.7, 3.8
-- **Django**: 1.11, 2.0, 2.1
-- **Python**: 2.7, 3.4, 3.5, 3.6, 3.7
+- **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
+
+Only the latest patch version of each ``major.minor`` series of Python, Django and Django REST Framework is supported.
+
+**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:
 
@@ -22,9 +31,7 @@ Resources:
 * **Changelog**: https://drf-yasg.readthedocs.io/en/stable/changelog.html
 * **Live demo**: https://drf-yasg-demo.herokuapp.com/
 
-.. image:: https://www.herokucdn.com/deploy/button.svg
-   :target: https://heroku.com/deploy?template=https://github.com/axnsan12/drf-yasg
-   :alt: heroku deploy button
+|heroku-button|
 
 ********
 Features
@@ -40,8 +47,7 @@ Features
   `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>`_
+  `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
 
@@ -114,6 +120,7 @@ In ``urls.py``:
 .. code:: python
 
    ...
+   from rest_framework import permissions
    from drf_yasg.views import get_schema_view
    from drf_yasg import openapi
 
@@ -128,7 +135,6 @@ In ``urls.py``:
          contact=openapi.Contact(email="contact@snippets.local"),
          license=openapi.License(name="BSD License"),
       ),
-      validators=['flex', 'ssv'],
       public=True,
       permission_classes=(permissions.AllowAny,),
    )
@@ -140,7 +146,7 @@ In ``urls.py``:
       ...
    ]
 
-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``
@@ -159,7 +165,7 @@ a. ``get_schema_view`` parameters
 - ``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
@@ -204,9 +210,9 @@ caching the schema view in-memory, with some sane defaults:
 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=['flex', 'ssv']` 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.
@@ -229,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
 
@@ -294,51 +300,12 @@ For additional usage examples, you can take a look at the test project in the ``
    $ 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 shell -c "import createsuperuser"
    (venv) $ python manage.py runserver
    (venv) $ firefox localhost:8000/swagger/
 
-**********
-Background
-**********
-
-``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.
-
-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>`__.
-
-From here on, the terms “OpenAPI” and “Swagger” are used interchangeably.
-
-Swagger in Django Rest Framework
-================================
-
-Since Django Rest Framework 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:
-
-* 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``, …
-
-In short this makes the generated schema unusable for code generation, and mediocre at best for documentation.
-
-Other libraries
-===============
-
-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>`__
-
-``django-rest-swagger`` is just a wrapper around DRF 3.7 schema generation with an added UI, and
-thus presents the same problems, while also being unmaintained. ``drf-openapi`` was
-`discontinued by the author <https://github.com/limdauto/drf_openapi/commit/1673c6e039eec7f089336a83bdc31613f32f7e21>`_
-on April 3rd, 2018.
-
 ************************
 Third-party integrations
 ************************
@@ -372,5 +339,13 @@ provided out of the box - if you have ``djangorestframework-recursive`` installe
    :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:

coverage.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-set -ex
-
-coverage combine
-coverage report
-codecov

docs/changelog.rst

@@ -3,6 +3,143 @@ 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**
 **********

docs/conf.py

@@ -48,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])
@@ -171,16 +176,19 @@ nitpick_ignore = [
     ('py:class', 'int'),
     ('py:class', 'bytes'),
     ('py:class', 'tuple'),
-    ('py:class', 'callable'),
+    ('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'),
 

docs/custom_spec.rst

@@ -45,6 +45,8 @@ some properties of the generated :class:`.Operation`. For example, in a ``ViewSe
 
 .. 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):
       """partial_update method docstring"""
@@ -87,14 +89,14 @@ 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, ``@action``\ s, ``@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-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/')
          @action(detail=False, methods=['get'])
          def today(self, request):
@@ -210,7 +212,8 @@ Schema generation of ``serializers.SerializerMethodField`` is supported in two w
 Serializer ``Meta`` nested class
 ********************************
 
-You can define some per-serializer options by adding a ``Meta`` class to your serializer, e.g.:
+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
 
@@ -234,6 +237,64 @@ The available options are:
      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
@@ -314,7 +375,7 @@ implemented like so:
    ))
    class ArticleViewSet(viewsets.ModelViewSet):
       filter_backends = (DjangoFilterBackend,)
-      filter_fields = ('title',)
+      filterset_fields = ('title',)
       ...
 
 
@@ -376,7 +437,7 @@ A second example, of a :class:`~.inspectors.FieldInspector` that removes the ``t
 
 
       class AnotherSerializer(serializers.ModelSerializer):
-         chilf = OneSerializer()
+         child = OneSerializer()
 
          class Meta:
             model = SomeParentModel
@@ -387,3 +448,5 @@ A second example, of a :class:`~.inspectors.FieldInspector` that removes the ``t
 
 
 .. _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/openapi.rst

@@ -14,7 +14,7 @@ This library generates OpenAPI 2.0 documents. The authoritative specification fo
 be the official documentation over at `swagger.io <https://swagger.io/>`__ and the `OpenAPI 2.0 specification
 page <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>`__.
 
-Beause the above specifications are a bit heavy and convoluted, here is a general overview of how the specification
+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

docs/security.rst

@@ -81,7 +81,7 @@ A very simple working configuration was provided by :ghuser:`Vigrond`, originall
             'type': 'oauth2',
             'authorizationUrl': '/yourapp/o/authorize',
             'tokenUrl': '/yourapp/o/token/',
-            'flow": "accessCode',
+            'flow': 'accessCode',
             'scopes': {
              'read:groups': 'read groups',
             }

docs/settings.rst

@@ -85,6 +85,7 @@ to this list.
 :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| \
@@ -229,7 +230,7 @@ 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|
+**Default**: :python:`False` |br|
 *Maps to parameter*: -
 
 REFETCH_SCHEMA_WITH_AUTH
@@ -237,7 +238,7 @@ REFETCH_SCHEMA_WITH_AUTH
 
 Re-fetch the OpenAPI document with the new credentials after authorization is performed through swagger-ui.
 
-**Default**: :python:`'False` |br|
+**Default**: :python:`False` |br|
 *Maps to parameter*: -
 
 REFETCH_SCHEMA_ON_LOGOUT
@@ -245,7 +246,7 @@ REFETCH_SCHEMA_ON_LOGOUT
 
 Re-fetch the OpenAPI document without credentials after authorization is removed through swagger-ui.
 
-**Default**: :python:`'False` |br|
+**Default**: :python:`False` |br|
 *Maps to parameter*: -
 
 FETCH_SCHEMA_WITH_QUERY
@@ -253,7 +254,7 @@ FETCH_SCHEMA_WITH_QUERY
 
 Fetch the OpenAPI document using the query parameters passed to the swagger-ui page request.
 
-**Default**: :python:`'True` |br|
+**Default**: :python:`True` |br|
 *Maps to parameter*: -
 
 OPERATIONS_SORTER
@@ -340,7 +341,7 @@ values for Parameters.
 OAUTH2_REDIRECT_URL
 -------------------
 
-Used when OAuth2 authenitcation of API requests via swagger-ui is desired. If ``None`` is passed, the
+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``.
@@ -351,7 +352,7 @@ file provided by ``swagger-ui``.
 OAUTH2_CONFIG
 -------------
 
-Used when OAuth2 authenitcation of API requests via swagger-ui is desired. Provides OAuth2 configuration parameters
+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>`_.
 
@@ -454,7 +455,7 @@ FETCH_SCHEMA_WITH_QUERY
 
 Fetch the OpenAPI document using the query parameters passed to the ReDoc page request.
 
-**Default**: :python:`'True` |br|
+**Default**: :python:`True` |br|
 *Maps to parameter*: -
 
 

package.json

@@ -1,8 +1,8 @@
 {
   "name": "drf-yasg",
   "dependencies": {
-    "redoc": "^2.0.0-alpha.41",
-    "swagger-ui-dist": "^3.20.1"
+    "redoc": "^2.0.0-rc.14",
+    "swagger-ui-dist": "^3.23.11"
   },
   "repository": {
     "type": "git",

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

@@ -1,3 +1,4 @@
--r requirements/setup.txt
+# 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

@@ -4,6 +4,7 @@ ruamel.yaml>=0.15.34
 inflection>=0.3.1
 six>=1.10.0
 uritemplate>=3.0.0
+packaging
 
-djangorestframework>=3.7.7
+djangorestframework>=3.8
 Django>=1.11.7

requirements/dev.txt

@@ -4,3 +4,4 @@
 -r lint.txt
 
 tox-battery>=0.5
+django-oauth-toolkit

requirements/docs.txt

@@ -2,7 +2,8 @@
 Sphinx>=1.7.0
 sphinx_rtd_theme>=0.2.4
 Pillow>=4.3.0
-readme_renderer>=17.2
+readme_renderer[md]>=24.0
+twine>=1.12.1
 
 Django>=2.0
 djangorestframework_camel_case>=0.2.0

requirements/setup.txt

@@ -1,3 +0,0 @@
-# needed to build the package setup_requires in setup.py
-
-setuptools-scm>=3.0.6

requirements/test.txt

@@ -1,9 +1,11 @@
 # requirements for running the tests via pytest
-pytest>=2.9,<3.7  # <3.7 because of incompatible pluggy requirement
+pytest>=4.0
 pytest-pythonpath>=0.7.1
-pytest-cov>=2.5.1
-pytest-xdist>=1.22.0
-pytest-django>=3.2.0
+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
 
 -r testproj.txt

requirements/testproj.txt

@@ -1,10 +1,9 @@
 # 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"
-djangorestframework-camel-case>=0.2.0
+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

@@ -1,4 +1,2 @@
 # requirements for building and running tox
-tox>=3.1.2
-
--r setup.txt
+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

@@ -1 +1 @@
-python-3.6.6
+python-3.7.3

setup.py

@@ -17,9 +17,20 @@ with io.open('README.rst', encoding='utf-8') as readme:
     description = readme.read()
 
 requirements = read_req('base.txt')
-requirements_setup = read_req('setup.txt')
 requirements_validation = read_req('validation.txt')
 
+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(
@@ -28,7 +39,6 @@ def drf_yasg_setup(**kwargs):
         package_dir={'': 'src'},
         include_package_data=True,
         install_requires=requirements,
-        setup_requires=requirements_setup,
         extras_require={
             'validation': requirements_validation,
         },
@@ -40,48 +50,47 @@ def drf_yasg_setup(**kwargs):
         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=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
+        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',
-            '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',
-            'Programming Language :: Python :: 3.7',
             '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 LookupError as e:
+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
 
-    if 'setuptools-scm' in str(e):
+    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 = '0.0.0rc0+noscm' + timestamp_str
+        dummy_version = '1!0.0.0.dev0+noscm.' + timestamp_str
 
         drf_yasg_setup(version=dummy_version)
-        print(str(e), file=sys.stderr)
-        print("failed to detect version, build was done using dummy version " + dummy_version, file=sys.stderr)
+
+        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/app_settings.py

@@ -12,6 +12,7 @@ SWAGGER_DEFAULTS = {
         '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',

src/drf_yasg/codecs.py

@@ -1,7 +1,8 @@
-from six import raise_from
+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
@@ -10,10 +11,16 @@ from ruamel import yaml
 from . import openapi
 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
+
     try:
         validate_flex(spec)
     except ValidationError as ex:
@@ -70,7 +77,10 @@ class _OpenAPICodec(object):
                 errors[validator] = str(e)
 
         if errors:
-            raise SwaggerValidationError("spec validation failed", errors, spec, self)
+            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):
@@ -82,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")
 
@@ -99,8 +109,21 @@ class _OpenAPICodec(object):
 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."""
+        """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)
 
 
@@ -121,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.
@@ -134,27 +156,34 @@ class SaneYamlDumper(yaml.SafeDumper):
         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)
 
@@ -170,7 +199,7 @@ def yaml_sane_dump(data, binary):
     :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)
 
@@ -196,6 +225,12 @@ def yaml_sane_load(stream):
 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/generators.py

@@ -3,22 +3,31 @@ import logging
 import re
 from collections import OrderedDict, defaultdict
 
+import rest_framework
 import uritemplate
 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 SchemaGenerator, endpoint_ordering
-from rest_framework.schemas.inspectors import get_pk_description
-from rest_framework.settings import api_settings as rest_framework_settings
+from rest_framework.schemas.generators import endpoint_ordering, get_pk_name
+from rest_framework.settings import api_settings
 
 from . import openapi
 from .app_settings import swagger_settings
 from .errors import SwaggerGenerationError
 from .inspectors.field import get_basic_type_info, get_queryset_field, get_queryset_from_view
-from .openapi import ReferenceResolver
+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+)}')
@@ -132,7 +141,7 @@ class EndpointEnumerator(_EndpointEnumerator):
 
     def unescape_path(self, path):
         """Remove backslashe escapes from all path components outside {parameters}. This is needed because
-        ``simplify_regex`` does not handle this correctly - note however that this implementation is
+        ``simplify_regex`` does not handle this correctly.
 
         **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
@@ -160,11 +169,12 @@ class OpenAPISchemaGenerator(object):
     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):
         """
 
-        :param .Info info: information about the 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
@@ -198,32 +208,56 @@ class OpenAPISchemaGenerator(object):
     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 a :class:`.Swagger` object representing the API schema.
 
-        :param 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)
-        self.consumes = get_consumes(rest_framework_settings.DEFAULT_PARSER_CLASSES)
-        self.produces = get_produces(rest_framework_settings.DEFAULT_RENDERER_CLASSES)
+        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)
 
-        security_definitions = swagger_settings.SECURITY_DEFINITIONS
-        if security_definitions is not None:
-            security_definitions = OrderedDict(sorted([(key, OrderedDict(sorted(sd.items())))
-                                                       for key, sd in swagger_settings.SECURITY_DEFINITIONS.items()]))
-        security_requirements = swagger_settings.SECURITY_REQUIREMENTS
-        if security_requirements is None:
-            security_requirements = [{security_scheme: []} for security_scheme in swagger_settings.SECURITY_DEFINITIONS]
-
-        security_requirements = sorted(security_requirements, key=lambda od: list(sorted(od)))
-        security_requirements = [OrderedDict(sorted(sr.items())) for sr in security_requirements]
+        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:
@@ -238,9 +272,10 @@ class OpenAPISchemaGenerator(object):
     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)
@@ -255,12 +290,31 @@ class OpenAPISchemaGenerator(object):
         setattr(view, 'swagger_fake_view', True)
         return view
 
+    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, request=request)
         endpoints = enumerator.get_api_endpoints()
@@ -269,7 +323,7 @@ class OpenAPISchemaGenerator(object):
         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()}
@@ -287,7 +341,7 @@ 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)
 
@@ -396,7 +450,7 @@ class OpenAPISchemaGenerator(object):
         if view_inspector_cls is None:
             return None
 
-        view_inspector = view_inspector_cls(view, path, method, components, request, overrides)
+        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

src/drf_yasg/inspectors/__init__.py

@@ -4,8 +4,8 @@ from .base import (
 )
 from .field import (
     CamelCaseJSONFilter, ChoiceFieldInspector, DictFieldInspector, FileFieldInspector, HiddenFieldInspector,
-    InlineSerializerInspector, RecursiveFieldInspector, ReferencingSerializerInspector, RelatedFieldInspector,
-    SerializerMethodFieldInspector, SimpleFieldInspector, StringDefaultFieldInspector
+    InlineSerializerInspector, JSONFieldInspector, RecursiveFieldInspector, ReferencingSerializerInspector,
+    RelatedFieldInspector, SerializerMethodFieldInspector, SimpleFieldInspector, StringDefaultFieldInspector
 )
 from .query import CoreAPICompatInspector, DjangoRestResponsePagination
 from .view import SwaggerAutoSchema
@@ -24,7 +24,7 @@ __all__ = [
 
     # field inspectors
     'InlineSerializerInspector', 'RecursiveFieldInspector', 'ReferencingSerializerInspector', 'RelatedFieldInspector',
-    'SimpleFieldInspector', 'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector',
+    'SimpleFieldInspector', 'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector', 'JSONFieldInspector',
     'StringDefaultFieldInspector', 'CamelCaseJSONFilter', 'HiddenFieldInspector', 'SerializerMethodFieldInspector',
 
     # view inspectors

src/drf_yasg/inspectors/base.py

@@ -4,7 +4,7 @@ import logging
 from rest_framework import serializers
 
 from .. import openapi
-from ..utils import force_real_str, get_field_default, is_list_view
+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()
@@ -12,14 +12,61 @@ 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 view: the view associated with this endpoint
+        :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 Request request: the request made against the schema view; can be None
+        :param rest_framework.request.Request request: the request made against the schema view; can be None
         """
         self.view = view
         self.path = path
@@ -81,6 +128,22 @@ class BaseInspector(object):
 
         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.
@@ -159,7 +222,7 @@ class FieldInspector(BaseInspector):
         :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,openapi.SchemaRef
+        :rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef
         """
         return NotHandled
 
@@ -168,7 +231,7 @@ class FieldInspector(BaseInspector):
 
         All arguments are the same as :meth:`.field_to_swagger_object`.
 
-        :rtype: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
+        :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},
@@ -203,13 +266,14 @@ class FieldInspector(BaseInspector):
             - :class:`.Schema` if `swagger_object_type` is :class:`.Schema`
             - :class:`.Items` if `swagger_object_type` is  :class:`.Parameter` or :class:`.Items`
 
-        :rtype: tuple[callable,(type[openapi.Schema],type[openapi.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
-        description = force_real_str(field.help_text) if field.help_text else None
+        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):
@@ -278,6 +342,9 @@ class ViewInspector(BaseInspector):
     #: 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 = []  #:
@@ -311,20 +378,30 @@ class ViewInspector(BaseInspector):
         """
         raise NotImplementedError("ViewInspector must implement get_operation()!")
 
-    # methods below provided as default implementations for probing inspectors
+    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
         """
-        if not getattr(self.view, 'filter_backends', None):
-            return False
-
-        if self.method.lower() not in ["get", "delete"]:
-            return False
-
-        return is_list_view(self.path, self.method, self.view)
+        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.
@@ -335,7 +412,7 @@ class ViewInspector(BaseInspector):
             return []
 
         fields = []
-        for filter_backend in self.view.filter_backends:
+        for filter_backend in getattr(self.view, 'filter_backends'):
             fields += self.probe_inspectors(self.filter_inspectors, 'get_filter_parameters', filter_backend()) or []
 
         return fields
@@ -345,13 +422,7 @@ class ViewInspector(BaseInspector):
 
         :rtype: bool
         """
-        if not getattr(self.view, 'paginator', None):
-            return False
-
-        if self.method.lower() != 'get':
-            return False
-
-        return is_list_view(self.path, self.method, self.view)
+        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.
@@ -361,14 +432,15 @@ class ViewInspector(BaseInspector):
         if not self.should_page():
             return []
 
-        return self.probe_inspectors(self.paginator_inspectors, 'get_paginator_parameters', self.view.paginator) or []
+        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,openapi.SchemaRef
+        :rtype: openapi.Schema or openapi.SchemaRef
         """
         return self.probe_inspectors(
             self.field_inspectors, 'get_schema', serializer, {'field_inspectors': self.field_inspectors}
@@ -394,4 +466,4 @@ class ViewInspector(BaseInspector):
         :rtype: openapi.Schema
         """
         return self.probe_inspectors(self.paginator_inspectors, 'get_paginated_response',
-                                     self.view.paginator, response_schema=response_schema)
+                                     getattr(self.view, 'paginator'), response_schema=response_schema)

src/drf_yasg/inspectors/field.py

@@ -2,6 +2,7 @@ import datetime
 import inspect
 import logging
 import operator
+import sys
 import uuid
 from collections import OrderedDict
 from decimal import Decimal
@@ -13,8 +14,10 @@ from rest_framework.settings import api_settings as rest_framework_settings
 
 from .. import openapi
 from ..errors import SwaggerGenerationError
-from ..utils import decimal_as_float, filter_none, get_serializer_class, get_serializer_ref_name
-from .base import FieldInspector, NotHandled, SerializerInspector
+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
@@ -58,6 +61,7 @@ class InlineSerializerInspector(SerializerInspector):
             )
             for key, value
             in fields.items()
+            if not getattr(value, 'read_only', False)
         ]
 
         return self.add_manual_parameters(serializer, parameters)
@@ -71,14 +75,20 @@ class InlineSerializerInspector(SerializerInspector):
     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:
@@ -115,6 +125,7 @@ class InlineSerializerInspector(SerializerInspector):
                     # 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:
@@ -124,11 +135,15 @@ class InlineSerializerInspector(SerializerInspector):
             actual_schema = definitions.setdefault(ref_name, make_schema_definition)
             actual_schema._remove_read_only()
 
-            actual_serializer = get_serializer_class(getattr(actual_schema, '_serializer', None))
+            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
-                logger.warning("Schema for %s will override distinct serializer %s because they "
-                               "share the same ref_name", actual_serializer, this_serializer)
+                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)
 
@@ -176,11 +191,11 @@ def get_queryset_from_view(view, serializer=None):
     :return: queryset or ``None``
     """
     try:
-        queryset = getattr(view, 'queryset', None)
+        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) == view.get_serializer_class()
+            assert type(serializer) == call_view_method(view, 'get_serializer_class', 'serializer_class')
 
         return queryset
     except Exception:  # pragma: no cover
@@ -367,8 +382,21 @@ def find_limits(field):
 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)),
@@ -454,18 +482,57 @@ def decimal_return_type():
     return openapi.TYPE_STRING if rest_framework_settings.COERCE_DECIMAL_TO_STRING else openapi.TYPE_NUMBER
 
 
-raw_type_info = [
+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)),
-    # TODO - support typing.List etc
 ]
 
-hinting_type_info = raw_type_info
+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):
@@ -477,28 +544,35 @@ def get_basic_type_info_from_hint(hint_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)
 
-    for check_class, type_format in hinting_type_info:
-        if issubclass(hint_class, check_class):
-            swagger_type, format = type_format
-            if callable(swagger_type):
-                swagger_type = swagger_type()
-            # if callable(format):
-            #     format = format(klass)
-            break
-    else:  # pragma: no cover
-        return None
-
-    pattern = None
-
-    result = OrderedDict([
-        ('type', swagger_type),
-        ('format', format),
-        ('pattern', pattern)
-    ])
+    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
@@ -513,12 +587,10 @@ class SerializerMethodFieldInspector(FieldInspector):
         if method is None:
             return NotHandled
 
+        # attribute added by the swagger_serializer_method decorator
         serializer = getattr(method, "_swagger_serializer", None)
 
         if serializer:
-            # attribute added by the swagger_serializer_method decorator
-            serializer = getattr(method, '_swagger_serializer', None)
-
             # in order of preference for description, use:
             # 1) field.help_text from SerializerMethodField(help_text)
             # 2) serializer.help_text from swagger_serializer_method(serializer)
@@ -586,18 +658,36 @@ class ChoiceFieldInspector(FieldInspector):
 
         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')
-                model_field = get_model_field(model, field.source)
+                # 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)
 
-            enum_values = list(field.choices.keys())
             if isinstance(field, serializers.MultipleChoiceField):
                 result = SwaggerType(
                     type=openapi.TYPE_ARRAY,
@@ -670,11 +760,23 @@ class HiddenFieldInspector(FieldInspector):
         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 JSONField
+        # TODO unhandled fields: TimeField
         SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
         return SwaggerType(type=openapi.TYPE_STRING)
 
@@ -727,8 +829,8 @@ class CamelCaseJSONFilter(FieldInspector):
     if CamelCaseJSONParser and CamelCaseJSONRenderer:
         def is_camel_case(self):
             return (
-                any(issubclass(parser, CamelCaseJSONParser) for parser in self.view.parser_classes) or
-                any(issubclass(renderer, CamelCaseJSONRenderer) for renderer in self.view.renderer_classes)
+                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):
@@ -749,10 +851,19 @@ else:
             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"
 
-                ref_name = get_serializer_ref_name(field.proxied)
-                assert ref_name is not None, "Can't create RecursiveField schema for inline " + str(type(field.proxied))
+                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)
-                return openapi.SchemaRef(definitions, ref_name, ignore_unresolved=True)
+
+                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

@@ -71,8 +71,8 @@ class DjangoRestResponsePagination(PaginatorInspector):
                 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)),
-                    ('previous', openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI)),
+                    ('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']

src/drf_yasg/inspectors/view.py

@@ -8,33 +8,35 @@ from rest_framework.status import is_success
 from .. import openapi
 from ..errors import SwaggerGenerationError
 from ..utils import (
-    force_real_str, force_serializer_instance, get_consumes, get_produces, guess_response_status, is_list_view,
+    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
+from .base import ViewInspector, call_view_method
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 
 class SwaggerAutoSchema(ViewInspector):
-    def __init__(self, view, path, method, components, request, overrides):
+    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
 
-    def get_operation(self, operation_keys):
         consumes = self.get_consumes()
         produces = self.get_produces()
 
         body = self.get_request_body_parameters(consumes)
         query = self.get_query_parameters()
         parameters = body + query
-        parameters = [param for param in parameters if param is not None]
+        parameters = filter_none(parameters)
         parameters = self.add_manual_parameters(parameters)
 
         operation_id = self.get_operation_id(operation_keys)
-        description = self.get_description()
-        summary = self.get_summary()
+        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()
@@ -87,21 +89,12 @@ class SwaggerAutoSchema(ViewInspector):
         """Return the serializer as defined by the view's ``get_serializer()`` method.
 
         :return: the view's ``Serializer``
+        :rtype: rest_framework.serializers.Serializer
         """
-        if not hasattr(self.view, 'get_serializer'):
-            return None
-        try:
-            return self.view.get_serializer()
-        except Exception:
-            log.warning("view's get_serializer raised exception (%s %s %s)",
-                        self.method, self.path, type(self.view).__name__, exc_info=True)
-            return None
+        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.
-
-        :return:
-        """
+        """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:
@@ -120,6 +113,7 @@ class SwaggerAutoSchema(ViewInspector):
         """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()
 
@@ -167,12 +161,13 @@ class SwaggerAutoSchema(ViewInspector):
         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):
+            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")
+                raise SwaggerGenerationError("form parameters can only be applied to "
+                                             "(" + ','.join(self.body_methods) + ") HTTP methods")
 
         return merge_params(parameters, manual_parameters)
 
@@ -216,7 +211,7 @@ class SwaggerAutoSchema(ViewInspector):
             default_schema = self.serializer_to_schema(default_schema) or ''
 
         if default_schema:
-            if is_list_view(self.path, self.method, self.view) and self.method.lower() == 'get':
+            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
@@ -308,7 +303,7 @@ class SwaggerAutoSchema(ViewInspector):
 
         return natural_parameters + serializer_parameters
 
-    def get_operation_id(self, operation_keys):
+    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.
 
@@ -316,12 +311,39 @@ class SwaggerAutoSchema(ViewInspector):
             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 _extract_description_and_summary(self):
+    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:
@@ -330,31 +352,9 @@ class SwaggerAutoSchema(ViewInspector):
 
             if description and (summary is None):
                 # description from docstring... do summary magic
-                # https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
-                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
+                summary, description = self.split_summary_from_description(description)
 
-        return description, summary
-
-    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
-        """
-        return self._extract_description_and_summary()[0]
-
-    def get_summary(self):
-        """Return a summary description for this operation.
-
-        :return: the summary
-        :rtype: str
-        """
-        return self._extract_description_and_summary()[1]
+        return summary, description
 
     def get_security(self):
         """Return a list of security requirements for this operation.
@@ -374,26 +374,33 @@ class SwaggerAutoSchema(ViewInspector):
         """
         return self.overrides.get('deprecated', None)
 
-    def get_tags(self, operation_keys):
+    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.
+        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]
         """
-        return [operation_keys[0]]
+        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(getattr(self.view, 'parser_classes', []))
+        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(getattr(self.view, 'renderer_classes', []))
+        return get_produces(self.get_renderer_classes())

src/drf_yasg/management/commands/generate_swagger.py

@@ -1,12 +1,11 @@
-import json
 import logging
 import os
-from collections import OrderedDict
-from importlib import import_module
 
 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
 
@@ -15,15 +14,6 @@ from ...app_settings import swagger_settings
 from ...codecs import OpenAPICodecJson, OpenAPICodecYaml
 
 
-def import_class(import_string):
-    if not import_string:
-        return None
-
-    module_path, class_name = import_string.rsplit('.', 1)
-    module = import_module(module_path)
-    return getattr(module, class_name)
-
-
 class Command(BaseCommand):
     help = 'Write the Swagger schema to disk in JSON or YAML format.'
 
@@ -43,7 +33,7 @@ class Command(BaseCommand):
         )
         parser.add_argument(
             '-f', '--format', dest='format',
-            default='', choices=('json', 'yaml'),
+            default='', choices=['json', 'yaml'],
             type=str,
             help='Output format. If not given, it is guessed from the output file extension and defaults to json.'
         )
@@ -85,11 +75,9 @@ class Command(BaseCommand):
 
     def write_schema(self, schema, stream, format):
         if format == 'json':
-            codec = OpenAPICodecJson(validators=[])
-            swagger_json = codec.encode(schema)
-            swagger_json = json.loads(swagger_json.decode('utf-8'), object_pairs_hook=OrderedDict)
-            pretty_json = json.dumps(swagger_json, indent=4, ensure_ascii=True)
-            stream.write(pretty_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')
@@ -107,6 +95,20 @@ class Command(BaseCommand):
         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
@@ -129,7 +131,7 @@ class Command(BaseCommand):
         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(username=user)
+            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:
@@ -142,22 +144,19 @@ class Command(BaseCommand):
         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_class = import_class(generator_class_name) or swagger_settings.DEFAULT_GENERATOR_CLASS
-        generator = generator_class(
-            info=info,
-            version=api_version,
-            url=api_url,
-        )
-        schema = generator.get_schema(request=request, public=not private)
+        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:

src/drf_yasg/openapi.py

@@ -1,12 +1,21 @@
+import six
+
+import collections
 import logging
 import re
 from collections import OrderedDict
 
 from coreapi.compat import urlparse
 from django.urls import get_script_prefix
+from django.utils.functional import Promise
 from inflection import camelize
 
-from .utils import filter_none
+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__)
 
@@ -128,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
@@ -149,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):
@@ -224,12 +243,12 @@ class Swagger(SwaggerDict):
         :param str _prefix: api path prefix to use in setting basePath; this will be appended to the wsgi
             SCRIPT_NAME prefix or Django's FORCE_SCRIPT_NAME if applicable
         :param str _version: version string to override Info
-        :param dict[str,dict[str,str]] security_definitions: list of supported authentication mechanisms
-        :param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation
+        :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
+        :param Paths paths: paths object
+        :param dict[str,Schema] definitions: named models
         """
         super(Swagger, self).__init__(**extra)
         self.swagger = '2.0'
@@ -280,7 +299,7 @@ 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():
@@ -297,14 +316,14 @@ class PathItem(SwaggerDict):
                  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
@@ -333,8 +352,8 @@ class Operation(SwaggerDict):
         """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 summary: operation summary; should be < 120 characters
@@ -355,6 +374,17 @@ class Operation(SwaggerDict):
         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.
@@ -371,12 +401,9 @@ class Items(SwaggerDict):
         self.format = format
         self.enum = enum
         self.pattern = pattern
-        self.items = items
+        self.items_ = items
         self._insert_extras__()
-        if items and type != TYPE_ARRAY:
-            raise AssertionError("items can only be used when type is array")
-        if pattern and type != TYPE_STRING:
-            raise AssertionError("pattern can only be used when type is string")
+        _check_type(type, format, enum, pattern, items, self.__class__)
 
 
 class Parameter(SwaggerDict):
@@ -389,7 +416,8 @@ 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
@@ -407,7 +435,7 @@ 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):
@@ -420,12 +448,9 @@ class Parameter(SwaggerDict):
             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 (format or enum or pattern or default) and not type:
-            raise AssertionError("[format, enum, pattern, default] can only be applied to non-body Parameter")
-        if items and type != TYPE_ARRAY:
-            raise AssertionError("items can only be used when type is array")
-        if pattern and type != TYPE_STRING:
-            raise AssertionError("pattern can only be used when type is string")
+        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):
@@ -441,10 +466,13 @@ class Schema(SwaggerDict):
         :param str format: value format, see OpenAPI spec
         :param list enum: restrict possible values
         :param str pattern: pattern if type is ``string``
-        :param dict[str,(.Schema,.SchemaRef)] properties: object properties; required if `type` is ``object``
-        :param bool,.Schema,.SchemaRef additional_properties: allow wildcard properties not listed in `properties`
-        :param list[str] required: list of requried property names
-        :param .Schema,.SchemaRef items: type of array 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``;
@@ -465,18 +493,13 @@ class Schema(SwaggerDict):
         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")
-        if (format or enum or pattern) and type in (TYPE_OBJECT, TYPE_ARRAY):
-            raise AssertionError("[format, enum, pattern] can only be applied to primitive Schema")
-        if items and type != TYPE_ARRAY:
-            raise AssertionError("items can only be used when type is array")
-        if pattern and type != TYPE_STRING:
-            raise AssertionError("pattern can only be used when type is string")
+        _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;
@@ -495,7 +518,7 @@ 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: allow the reference to be not defined 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"
@@ -530,7 +553,7 @@ class SchemaRef(_Ref):
 
         :param .ReferenceResolver resolver: component resolver which must contain the definition
         :param str schema_name: schema name
-        :param bool ignore_unresolved: allow the reference to be not defined in resolver
+        :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, ignore_unresolved)
@@ -542,7 +565,8 @@ 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 SwaggerDict,_Ref ref_or_obj:
+    :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):
@@ -554,8 +578,9 @@ 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():
@@ -570,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)
@@ -591,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:
@@ -615,7 +652,7 @@ class ReferenceResolver(object):
         :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
@@ -643,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)

src/drf_yasg/renderers.py

@@ -1,9 +1,11 @@
 import six
 
-from django.shortcuts import render, resolve_url
+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 json
+from rest_framework.utils import encoders, json
 
 from .app_settings import redoc_settings, swagger_settings
 from .codecs import VALIDATORS, OpenAPICodecJson, OpenAPICodecYaml
@@ -31,6 +33,7 @@ class _SpecRenderer(BaseRenderer):
             # 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)
 
 
@@ -67,13 +70,14 @@ class _UIRenderer(BaseRenderer):
             # 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)
+
         self.set_context(renderer_context, swagger)
-        return render(renderer_context['request'], self.template, renderer_context)
+        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())
+        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())
 
@@ -117,7 +121,14 @@ class SwaggerUIRenderer(_UIRenderer):
 
     def set_context(self, renderer_context, swagger=None):
         super(SwaggerUIRenderer, self).set_context(renderer_context, swagger)
-        renderer_context['swagger_settings'] = json.dumps(self.get_swagger_ui_settings())
+        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 = {
@@ -154,7 +165,7 @@ class ReDocRenderer(_UIRenderer):
 
     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())
+        renderer_context['redoc_settings'] = json.dumps(self.get_redoc_settings(), cls=encoders.JSONEncoder)
 
     def get_redoc_settings(self):
         data = {

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

@@ -2,6 +2,17 @@
 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({});
 
@@ -56,8 +67,7 @@ function initSwaggerUi() {
     }
     if (document.querySelector('.auth-wrapper .authorize')) {
         patchSwaggerUi();
-    }
-    else {
+    } else {
         insertionQ('.auth-wrapper .authorize').every(patchSwaggerUi);
     }
 
@@ -114,9 +124,9 @@ function initSwaggerUiConfig(swaggerSettings, oauth2Settings) {
     }
     if (persistAuth) {
         try {
-            savedAuth = Immutable.fromJS(JSON.parse(localStorage.getItem("drf-yasg-auth")) || {});
+            savedAuth = Immutable.fromJS(JSON.parse(localStorage.getItem(KEY_AUTH)) || {});
         } catch (e) {
-            localStorage.removeItem("drf-yasg-auth");
+            localStorage.removeItem(KEY_AUTH);
         }
     }
     if (refetchWithAuth) {
@@ -182,7 +192,6 @@ function initSwaggerUiConfig(swaggerSettings, oauth2Settings) {
         var oldResponseInterceptor = swaggerUiConfig.responseInterceptor;
         swaggerUiConfig.responseInterceptor = function (response) {
             var absUrl = new URL(response.url, currentPath);
-            console.log("response", response);
             if (absUrl.href in specRequestsInFlight) {
                 var setToUrl = specRequestsInFlight[absUrl.href];
                 delete specRequestsInFlight[absUrl.href];
@@ -278,8 +287,7 @@ function applyAuth(authorization, requestUrl, requestHeaders) {
                 if (_in === "query") {
                     if (requestUrl) {
                         requestUrl = setQueryParam(requestUrl, paramName, key);
-                    }
-                    else {
+                    } else {
                         console.warn("WARNING: cannot apply apiKey query parameter via interceptor");
                     }
                 }
@@ -343,7 +351,7 @@ function hookAuthActions(sui, persistAuth, refetchWithAuth, refetchOnLogout) {
             sui.authActions.showDefinitions(); // hide authorize dialog
         }
         if (persistAuth) {
-            localStorage.setItem("drf-yasg-auth", JSON.stringify(savedAuth.toJSON()));
+            localStorage.setItem(KEY_AUTH, JSON.stringify(savedAuth.toJSON()));
         }
     };
 
@@ -368,7 +376,7 @@ function hookAuthActions(sui, persistAuth, refetchWithAuth, refetchOnLogout) {
             sui.authActions.showDefinitions(); // hide authorize dialog
         }
         if (persistAuth) {
-            localStorage.setItem("drf-yasg-auth", JSON.stringify(savedAuth.toJSON()));
+            localStorage.setItem(KEY_AUTH, JSON.stringify(savedAuth.toJSON()));
         }
         originalLogout(authorization);
     };

src/drf_yasg/utils.py

@@ -1,11 +1,15 @@
 import inspect
 import logging
+import sys
+import textwrap
 from collections import OrderedDict
+from decimal import Decimal
 
 from django.db import models
-from django.utils.encoding import force_text
+from django.utils.encoding import force_str
 from rest_framework import serializers, status
-from rest_framework.mixins import DestroyModelMixin, RetrieveModelMixin, UpdateModelMixin
+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
@@ -29,7 +33,7 @@ class unset(object):
 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, **extra_overrides):
+                        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
@@ -39,11 +43,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
 
     :param str method: for multi-method views, the http method the options should apply to
     :param list[str] methods: for multi-method views, the http methods the options should apply to
-    :param .inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object;
+    :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 .Schema,.SchemaRef,.Serializer request_body: custom request body, or :class:`.no_body`. The value given here
-        will be used as the ``schema`` property of a :class:`.Parameter` with ``in: 'body'``.
+    :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
@@ -51,9 +55,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
 
         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 .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.
+    :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.
@@ -61,7 +67,8 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
         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
+    :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.
@@ -75,7 +82,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
         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 dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: a dict of documented manual responses
+    :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.
@@ -89,13 +96,16 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
         * 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[.FieldInspector] field_inspectors: extra serializer and field inspectors; these will be tried
-        before :attr:`.ViewInspector.field_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance
-    :param list[.FilterInspector] filter_inspectors: extra filter inspectors; these will be tried before
-        :attr:`.ViewInspector.filter_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance
-    :param list[.PaginatorInspector] paginator_inspectors: extra paginator inspectors; these will be tried before
-        :attr:`.ViewInspector.paginator_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance
+    :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``
     """
@@ -115,6 +125,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
             '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:
@@ -156,7 +167,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
 
             if len(available_http_methods) > 1:
                 assert _methods, \
-                    "on multi-method api_view, action, detail_route or list_route, you must specify " \
+                    "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
@@ -169,8 +180,8 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
             view_method._swagger_auto_schema = existing_data
         else:
             assert not _methods, \
-                "the methods argument should only be specified when decorating an action, detail_route or " \
-                "list_route; you should also ensure that you put the swagger_auto_schema decorator " \
+                "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
@@ -205,9 +216,9 @@ 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':
@@ -217,6 +228,9 @@ def is_list_view(path, method, view):
         # a detail action is surely not a list route
         return False
 
+    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
@@ -245,9 +259,9 @@ 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"
@@ -260,10 +274,10 @@ def merge_params(parameters, overrides):
 
     Raises an ``AssertionError`` if either list contains duplicate parameters.
 
-    :param list[.Parameter] parameters: initial parameters
-    :param list[.Parameter] overrides: overriding parameters
+    :param list[drf_yasg.openapi.Parameter] parameters: initial parameters
+    :param list[drf_yasg.openapi.Parameter] overrides: overriding parameters
     :return: merged list
-    :rtype: list[.Parameter]
+    :rtype: list[drf_yasg.openapi.Parameter]
     """
     parameters = param_list_to_odict(parameters)
     parameters.update(param_list_to_odict(overrides))
@@ -293,6 +307,7 @@ def force_serializer_instance(serializer):
     an assertion error.
 
     :param serializer: serializer class or instance
+    :type serializer: serializers.BaseSerializer or type[serializers.BaseSerializer]
     :return: serializer instance
     :rtype: serializers.BaseSerializer
     """
@@ -325,28 +340,62 @@ def get_serializer_class(serializer):
     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 []]
-    if all(is_form_media_type(encoding) for encoding in media_types):
-        return media_types
-    else:
-        media_types = [encoding for encoding in media_types if not is_form_media_type(encoding)]
+    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)]
@@ -354,8 +403,7 @@ def get_produces(renderer_classes):
 
 
 def decimal_as_float(field):
-    """
-    Returns true if ``field`` is a django-rest-framework DecimalField and its ``coerce_to_string`` attribute or the
+    """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
@@ -366,12 +414,11 @@ def decimal_as_float(field):
 
 
 def get_serializer_ref_name(serializer):
-    """
-    Get serializer's ref_name (or None for ModelSerializer if it is named 'NestedSerializer')
+    """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
+    :rtype: str or None
     """
     serializer_meta = getattr(serializer, 'Meta', None)
     serializer_name = type(serializer).__name__
@@ -394,13 +441,35 @@ def force_real_str(s, encoding='utf-8', strings_only=False, errors='strict'):
     Fix for https://github.com/axnsan12/drf-yasg/issues/159
     """
     if s is not None:
-        s = force_text(s, encoding, strings_only, errors)
+        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.
@@ -414,6 +483,9 @@ def get_field_default(field):
             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 "
@@ -422,15 +494,23 @@ def get_field_default(field):
 
         if default is not serializers.empty and default is not None:
             try:
-                default = field.to_representation(default)
-                # JSON roundtrip ensures that the value is valid JSON;
-                # for example, sets and tuples get transformed into lists
-                default = json.loads(json.dumps(default, cls=encoders.JSONEncoder))
-                if decimal_as_float(field):
-                    default = float(default)
+                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
@@ -30,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)
 
@@ -57,12 +56,12 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal
     :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; allowed values are ``flex``, ``ssv``
+    :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 or swagger_settings.DEFAULT_GENERATOR_CLASS
@@ -112,7 +111,7 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal
         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
@@ -131,7 +130,7 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal
         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
@@ -143,7 +142,7 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal
         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/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

@@ -20,6 +20,7 @@ class Article(models.Model):
                               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):

testproj/articles/serializers.py

@@ -1,4 +1,4 @@
-from django.utils.translation import ugettext_lazy as _
+from django.utils.translation import gettext_lazy as _
 from rest_framework import serializers
 
 from articles.models import Article, ArticleGroup
@@ -17,10 +17,9 @@ class ArticleSerializer(serializers.ModelSerializer):
 
     class Meta:
         model = Article
-        fields = ('title', 'author', 'body', 'slug', 'date_created', 'date_modified',
+        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_fields = ('date_created', 'date_modified', 'references', 'uuid', 'cover_name', 'read_only_nullable')
         lookup_field = 'slug'
         extra_kwargs = {
             'body': {'help_text': 'body serializer help_text'},
@@ -29,10 +28,12 @@ class ArticleSerializer(serializers.ModelSerializer):
                 '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):
+    image_id = serializers.UUIDField(read_only=True)
     what_am_i_doing = serializers.RegexField(
         regex=r"^69$",
         help_text="test",

testproj/articles/views.py

@@ -3,11 +3,9 @@ import datetime
 from django.utils.decorators import method_decorator
 from django_filters.rest_framework import DjangoFilterBackend
 from rest_framework import viewsets
-# noinspection PyDeprecation
-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
@@ -62,7 +60,7 @@ class ArticlePagination(LimitOffsetPagination):
 
 @method_decorator(name='list', decorator=swagger_auto_schema(
     operation_description="description from swagger_auto_schema via method_decorator",
-    filter_inspectors=[DjangoFilterDescriptionInspector]
+    filter_inspectors=[DjangoFilterDescriptionInspector],
 ))
 class ArticleViewSet(viewsets.ModelViewSet):
     """
@@ -84,13 +82,15 @@ 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_schema = NoTitleAutoSchema
 
-    try:
     from rest_framework.decorators import action
 
     @swagger_auto_schema(auto_schema=NoPagingAutoSchema, filter_inspectors=[DjangoFilterDescriptionInspector])
@@ -104,29 +104,12 @@ class ArticleViewSet(viewsets.ModelViewSet):
 
     @swagger_auto_schema(method='get', operation_description="image GET description override")
     @swagger_auto_schema(method='post', request_body=serializers.ImageUploadSerializer)
-        @action(detail=True, methods=['get', 'post'], parser_classes=(MultiPartParser,))
-        def image(self, request, slug=None):
-            """
-            image method docstring
-            """
-            pass
-    except ImportError:
-        action = None
-
-        # noinspection PyDeprecation
-        @swagger_auto_schema(auto_schema=NoPagingAutoSchema, filter_inspectors=[DjangoFilterDescriptionInspector])
-        @list_route(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)
-            articles = self.get_queryset().filter(date_created__range=(today_min, today_max)).all()
-            serializer = self.serializer_class(articles, many=True)
-            return Response(serializer.data)
-
-        # noinspection PyDeprecation
-        @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

testproj/createsuperuser.py

@@ -1,15 +0,0 @@
-from __future__ import print_function
-
-from django.contrib.auth.models import User
-from django.db.utils import IntegrityError
-
-username = 'admin'
-email = 'admin@admin.admin'
-password = 'passwordadmin'
-
-try:
-    User.objects.create_superuser(username, email, password)
-except IntegrityError:
-    print("User '%s <%s>' already exists" % (username, email))
-else:
-    print("Created superuser '%s <%s>' with password '%s'" % (username, email, password))

testproj/manage.py

@@ -7,9 +7,6 @@ if __name__ == "__main__":
     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/views.py

@@ -1,13 +1,19 @@
 from rest_framework import viewsets
+from rest_framework.pagination import BasePagination
 
 from .models import Identity, Person
 from .serializers import IdentitySerializer, PersonSerializer
 
 
+class UnknownPagination(BasePagination):
+    paginator_query_args = ['unknown_paginator']
+
+
 class PersonViewSet(viewsets.ModelViewSet):
     model = Person
     queryset = Person.objects
     serializer_class = PersonSerializer
+    pagination_class = UnknownPagination
 
 
 class IdentityViewSet(viewsets.ModelViewSet):

testproj/snippets/migrations/0003_snippetviewer.py

@@ -0,0 +1,24 @@
+# Generated by Django 2.1.7 on 2019-03-16 14:06
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('snippets', '0002_auto_20181219_1016'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='SnippetViewer',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('snippet', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='viewers', to='snippets.Snippet')),
+                ('viewer', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='snippet_views', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+    ]

testproj/snippets/migrations/0004_auto_20190613_0154.py

@@ -0,0 +1,23 @@
+# Generated by Django 2.2.2 on 2019-06-12 22:54
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('snippets', '0003_snippetviewer'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='snippet',
+            name='language',
+            field=models.CharField(choices=[('cpp', 'cpp'), ('js', 'js'), ('python', 'python')], default='python', max_length=100),
+        ),
+        migrations.AlterField(
+            model_name='snippet',
+            name='style',
+            field=models.CharField(choices=[('monokai', 'monokai'), ('solarized-dark', 'solarized-dark'), ('vim', 'vim')], default='solarized-dark', max_length=100),
+        ),
+    ]

testproj/snippets/models.py

@@ -1,10 +1,7 @@
 from django.db import models
-from pygments.lexers import get_all_lexers
-from pygments.styles import get_all_styles
 
-LEXERS = [item for item in get_all_lexers() if item[1]]
-LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS])
-STYLE_CHOICES = sorted((item, item) for item in get_all_styles())
+LANGUAGE_CHOICES = sorted((item, item) for item in ('cpp', 'python', 'js'))
+STYLE_CHOICES = sorted((item, item) for item in ('solarized-dark', 'monokai', 'vim'))
 
 
 class Snippet(models.Model):
@@ -14,7 +11,12 @@ class Snippet(models.Model):
     code = models.TextField(help_text="code model help text")
     linenos = models.BooleanField(default=False)
     language = models.CharField(choices=LANGUAGE_CHOICES, default='python', max_length=100)
-    style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100)
+    style = models.CharField(choices=STYLE_CHOICES, default='solarized-dark', max_length=100)
 
     class Meta:
         ordering = ('created',)
+
+
+class SnippetViewer(models.Model):
+    snippet = models.ForeignKey(Snippet, on_delete=models.CASCADE, related_name='viewers')
+    viewer = models.ForeignKey('auth.User', related_name='snippet_views', on_delete=models.CASCADE)

testproj/snippets/serializers.py

@@ -1,22 +1,29 @@
 from decimal import Decimal
 
+import rest_framework
 from django.contrib.auth import get_user_model
+from packaging.version import Version
 from rest_framework import serializers
-from rest_framework.compat import MinValueValidator
 
-from snippets.models import LANGUAGE_CHOICES, STYLE_CHOICES, Snippet
+from snippets.models import LANGUAGE_CHOICES, STYLE_CHOICES, Snippet, SnippetViewer
+
+if Version(rest_framework.__version__) < Version('3.10'):
+    from rest_framework.compat import MaxLengthValidator, MinValueValidator
+else:
+    from django.core.validators import MaxLengthValidator, MinValueValidator
 
 
 class LanguageSerializer(serializers.Serializer):
     name = serializers.ChoiceField(
         choices=LANGUAGE_CHOICES, default='python', help_text='The name of the programming language')
+    read_only_nullable = serializers.CharField(read_only=True, allow_null=True)
 
     class Meta:
         ref_name = None
 
 
 class ExampleProjectSerializer(serializers.Serializer):
-    project_name = serializers.CharField(help_text='Name of the project')
+    project_name = serializers.CharField(label='project name custom title', help_text='Name of the project')
     github_repo = serializers.CharField(required=True, help_text='Github repository of the project')
 
     class Meta:
@@ -65,11 +72,13 @@ class SnippetSerializer(serializers.Serializer):
     )
     title = serializers.CharField(required=False, allow_blank=True, max_length=100)
     code = serializers.CharField(style={'base_template': 'textarea.html'})
+    tags = serializers.ListField(child=serializers.CharField(min_length=2), min_length=3, max_length=15)
     linenos = serializers.BooleanField(required=False)
     language = LanguageSerializer(help_text="Sample help text for language")
-    styles = serializers.MultipleChoiceField(choices=STYLE_CHOICES, default=['friendly'])
+    styles = serializers.MultipleChoiceField(choices=STYLE_CHOICES, default=['solarized-dark'])
     lines = serializers.ListField(child=serializers.IntegerField(), allow_empty=True, allow_null=True, required=False)
-    example_projects = serializers.ListSerializer(child=ExampleProjectSerializer(), read_only=True)
+    example_projects = serializers.ListSerializer(child=ExampleProjectSerializer(), read_only=True,
+                                                  validators=[MaxLengthValidator(100)])
     difficulty_factor = serializers.FloatField(help_text="this is here just to test FloatField",
                                                read_only=True, default=lambda: 6.9)
     rate_as_string = serializers.DecimalField(max_digits=6, decimal_places=3, default=Decimal('0.0'),
@@ -97,3 +106,9 @@ class SnippetSerializer(serializers.Serializer):
         instance.style = validated_data.get('style', instance.style)
         instance.save()
         return instance
+
+
+class SnippetViewerSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = SnippetViewer
+        fields = '__all__'

testproj/snippets/urls.py

@@ -8,10 +8,13 @@ if django.VERSION[:2] >= (2, 0):
     urlpatterns = [
         path('', views.SnippetList.as_view()),
         path('<int:pk>/', views.SnippetDetail.as_view()),
+        path('views/<int:snippet_pk>/', views.SnippetViewerList.as_view()),
     ]
 else:
     from django.conf.urls import url
+
     urlpatterns = [
         url('^$', views.SnippetList.as_view()),
         url(r'^(?P<pk>\d+)/$', views.SnippetDetail.as_view()),
+        url(r'^views/(?P<snippet_pk>\d+)/$', views.SnippetViewerList.as_view()),
     ]

testproj/snippets/views.py

@@ -2,13 +2,15 @@ from djangorestframework_camel_case.parser import CamelCaseJSONParser
 from djangorestframework_camel_case.render import CamelCaseJSONRenderer
 from inflection import camelize
 from rest_framework import generics, status
-from rest_framework.parsers import FormParser
+from rest_framework.generics import get_object_or_404
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.parsers import FileUploadParser, FormParser
 
 from drf_yasg import openapi
 from drf_yasg.inspectors import SwaggerAutoSchema
 from drf_yasg.utils import swagger_auto_schema
-from snippets.models import Snippet
-from snippets.serializers import SnippetSerializer
+from snippets.models import Snippet, SnippetViewer
+from snippets.serializers import SnippetSerializer, SnippetViewerSerializer
 
 
 class CamelCaseOperationIDAutoSchema(SwaggerAutoSchema):
@@ -22,7 +24,7 @@ class SnippetList(generics.ListCreateAPIView):
     queryset = Snippet.objects.all()
     serializer_class = SnippetSerializer
 
-    parser_classes = (FormParser, CamelCaseJSONParser,)
+    parser_classes = (FormParser, CamelCaseJSONParser, FileUploadParser)
     renderer_classes = (CamelCaseJSONRenderer,)
     swagger_schema = CamelCaseOperationIDAutoSchema
 
@@ -83,11 +85,6 @@ class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
                 description="path parameter override",
                 required=True
             ),
-            openapi.Parameter(
-                name='delete_form_param', in_=openapi.IN_FORM,
-                type=openapi.TYPE_INTEGER,
-                description="this should not crash (form parameter on DELETE method)"
-            ),
         ],
         responses={
             status.HTTP_204_NO_CONTENT: openapi.Response(
@@ -98,3 +95,31 @@ class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
     def delete(self, request, *args, **kwargs):
         """delete method docstring"""
         return super(SnippetDetail, self).patch(request, *args, **kwargs)
+
+
+class SnippetViewerList(generics.ListAPIView):
+    """SnippetViewerList classdoc"""
+    serializer_class = SnippetViewerSerializer
+    pagination_class = PageNumberPagination
+
+    parser_classes = (FormParser, CamelCaseJSONParser, FileUploadParser)
+    renderer_classes = (CamelCaseJSONRenderer,)
+    swagger_schema = CamelCaseOperationIDAutoSchema
+    lookup_url_kwarg = 'snippet_pk'
+
+    def get_object(self):
+        queryset = Snippet.objects.all()
+
+        # Perform the lookup filtering.
+        lookup_url_kwarg = self.lookup_url_kwarg or self.lookup_field
+
+        filter_kwargs = {self.lookup_field: self.kwargs[lookup_url_kwarg]}
+        obj = get_object_or_404(queryset, **filter_kwargs)
+
+        # May raise a permission denied
+        self.check_object_permissions(self.request, obj)
+
+        return obj
+
+    def get_queryset(self):
+        return SnippetViewer.objects.filter(snippet=self.get_object())

testproj/testproj/inspectors.py

@@ -0,0 +1,11 @@
+from drf_yasg import openapi
+from drf_yasg.inspectors import NotHandled, PaginatorInspector
+
+
+class UnknownPaginatorInspector(PaginatorInspector):
+    def get_paginator_parameters(self, paginator):
+        if hasattr(paginator, 'paginator_query_args'):
+            return [openapi.Parameter(name=arg, in_=openapi.IN_QUERY, type=openapi.TYPE_STRING)
+                    for arg in getattr(paginator, 'paginator_query_args')]
+
+        return NotHandled

testproj/testproj/settings/base.py

@@ -3,6 +3,8 @@ import os
 # Build paths inside the project like this: os.path.join(BASE_DIR, ...)
 from django.urls import reverse_lazy
 
+from testproj.util import static_lazy
+
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 ALLOWED_HOSTS = [
@@ -22,6 +24,7 @@ INSTALLED_APPS = [
     'django.contrib.messages',
     'django.contrib.staticfiles',
     'rest_framework',
+    'oauth2_provider',
     'corsheaders',
 
     'drf_yasg',
@@ -64,9 +67,9 @@ TEMPLATES = [
 
 WSGI_APPLICATION = 'testproj.wsgi.application'
 
-# Password validation
-# https://docs.djangoproject.com/en/1.11/ref/settings/#auth-password-validators
+LOGIN_URL = reverse_lazy('admin:login')
 
+# Password validation
 AUTH_PASSWORD_VALIDATORS = [
     {
         'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
@@ -83,15 +86,22 @@ AUTH_PASSWORD_VALIDATORS = [
 ]
 
 # Django Rest Framework
-
 REST_FRAMEWORK = {
     'DEFAULT_PERMISSION_CLASSES': (
         'rest_framework.permissions.IsAuthenticated',
     )
 }
 
-# drf-yasg
+OAUTH2_CLIENT_ID = '12ee6bgxtpSEgP8TioWcHSXOiDBOUrVav4mRbVEs'
+OAUTH2_CLIENT_SECRET = '5FvYALo7W4uNnWE2ySw7Yzpkxh9PSf5GuY37RvOys00ydEyph64dbl1ECOKI9ceQ' \
+                       'AKoz0JpiVQtq0DUnsxNhU3ubrJgZ9YbtiXymbLGJq8L7n4fiER7gXbXaNSbze3BN'
+OAUTH2_APP_NAME = 'drf-yasg OAuth2 provider'
 
+OAUTH2_REDIRECT_URL = static_lazy('drf-yasg/swagger-ui-dist/oauth2-redirect.html')
+OAUTH2_AUTHORIZE_URL = reverse_lazy('oauth2_provider:authorize')
+OAUTH2_TOKEN_URL = reverse_lazy('oauth2_provider:token')
+
+# drf-yasg
 SWAGGER_SETTINGS = {
     'LOGIN_URL': reverse_lazy('admin:login'),
     'LOGOUT_URL': '/admin/logout',
@@ -106,16 +116,36 @@ SWAGGER_SETTINGS = {
             'type': 'basic'
         },
         'Bearer': {
-            'type': 'apiKey',
+            'in': 'header',
             'name': 'Authorization',
-            'in': 'header'
+            'type': 'apiKey',
+        },
+        'OAuth2 password': {
+            'flow': 'password',
+            'scopes': {
+                'read': 'Read everything.',
+                'write': 'Write everything,',
+            },
+            'tokenUrl': OAUTH2_TOKEN_URL,
+            'type': 'oauth2',
         },
         'Query': {
-            'type': 'apiKey',
+            'in': 'query',
             'name': 'auth',
-            'in': 'query'
-        }
-    }
+            'type': 'apiKey',
+        },
+    },
+    'OAUTH2_REDIRECT_URL': OAUTH2_REDIRECT_URL,
+    'OAUTH2_CONFIG': {
+        'clientId': OAUTH2_CLIENT_ID,
+        'clientSecret': OAUTH2_CLIENT_SECRET,
+        'appName': OAUTH2_APP_NAME,
+    },
+    "DEFAULT_PAGINATOR_INSPECTORS": [
+        'testproj.inspectors.UnknownPaginatorInspector',
+        'drf_yasg.inspectors.DjangoRestResponsePagination',
+        'drf_yasg.inspectors.CoreAPICompatInspector',
+    ]
 }
 
 REDOC_SETTINGS = {
@@ -123,21 +153,13 @@ REDOC_SETTINGS = {
 }
 
 # Internationalization
-# https://docs.djangoproject.com/en/1.11/topics/i18n/
-
 LANGUAGE_CODE = 'en-us'
-
 TIME_ZONE = 'UTC'
-
 USE_I18N = True
-
 USE_L10N = True
-
 USE_TZ = True
 
 # Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/1.11/howto/static-files/
-
 STATIC_URL = '/static/'
 STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
 STATICFILES_DIRS = [
@@ -145,11 +167,9 @@ STATICFILES_DIRS = [
 ]
 
 # Testing
-
 TEST_RUNNER = 'testproj.runner.PytestTestRunner'
 
 # Logging configuration
-
 LOGGING = {
     'version': 1,
     'disable_existing_loggers': True,
@@ -173,16 +193,6 @@ LOGGING = {
             'propagate': False,
         },
         'django': {
-            'handlers': ['console_log'],
-            'level': 'DEBUG',
-            'propagate': False,
-        },
-        'django.db.backends': {
-            'handlers': ['console_log'],
-            'level': 'INFO',
-            'propagate': False,
-        },
-        'django.template': {
             'handlers': ['console_log'],
             'level': 'INFO',
             'propagate': False,

testproj/testproj/settings/heroku.py

@@ -23,8 +23,6 @@ STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
 MIDDLEWARE.insert(0, 'whitenoise.middleware.WhiteNoiseMiddleware')
 
 # Database
-# https://docs.djangoproject.com/en/1.11/ref/settings/#databases
-
 DATABASES = {
     'default': dj_database_url.config(conn_max_age=600)
 }

testproj/testproj/settings/local.py

@@ -15,7 +15,6 @@ DATABASES = {
 }
 
 # Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/1.11/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
 SECRET_KEY = '!z1yj(9uz)zk0gg@5--j)bc4h^i!8))r^dezco8glf190e0&#p'

testproj/testproj/urls.py

@@ -47,6 +47,12 @@ def root_redirect(request):
     return redirect(schema_view, permanent=True)
 
 
+# urlpatterns required for settings values
+required_urlpatterns = [
+    url(r'^admin/', admin.site.urls),
+    url(r'^o/', include('oauth2_provider.urls', namespace='oauth2_provider')),
+]
+
 urlpatterns = [
     url(r'^swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=0), name='schema-json'),
     url(r'^swagger/$', SchemaView.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
@@ -59,11 +65,10 @@ urlpatterns = [
 
     url(r'^$', root_redirect),
 
-    url(r'^admin/', admin.site.urls),
     url(r'^snippets/', include('snippets.urls')),
     url(r'^articles/', include('articles.urls')),
     url(r'^users/', include('users.urls')),
     url(r'^todo/', include('todo.urls')),
     url(r'^people/', include('people.urls')),
     url(r'^plain/', plain_view),
-]
+] + required_urlpatterns

testproj/testproj/util.py

@@ -0,0 +1,4 @@
+from django.templatetags.static import static
+from django.utils.functional import lazy
+
+static_lazy = lazy(static, str)

testproj/todo/migrations/0003_pack.py

@@ -0,0 +1,21 @@
+# Generated by Django 2.1.5 on 2019-04-01 00:28
+
+from decimal import Decimal
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('todo', '0002_todotree'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Pack',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('size_code', models.DecimalField(choices=[(Decimal('50'), '5x10'), (Decimal('100'), '10x10'), (Decimal('200'), '10x20')], decimal_places=3, default=Decimal('200'), max_digits=7)),
+            ],
+        ),
+    ]

testproj/todo/models.py

@@ -1,3 +1,5 @@
+from decimal import Decimal
+
 from django.db import models
 
 
@@ -18,3 +20,19 @@ class TodoYetAnother(models.Model):
 class TodoTree(models.Model):
     parent = models.ForeignKey('self', on_delete=models.CASCADE, related_name='children', null=True)
     title = models.CharField(max_length=50)
+
+
+class Pack(models.Model):
+    SIZE_10x20 = Decimal(200.000)
+    SIZE_10x10 = Decimal(100.000)
+    SIZE_5x10 = Decimal(50.000)
+
+    size_code_choices = (
+        (SIZE_5x10, '5x10'),
+        (SIZE_10x10, '10x10'),
+        (SIZE_10x20, '10x20'),
+    )
+    size_code = models.DecimalField(max_digits=7,
+                                    decimal_places=3,
+                                    choices=size_code_choices,
+                                    default=SIZE_10x20)

testproj/todo/serializer.py

@@ -4,7 +4,7 @@ from django.utils import timezone
 from rest_framework import serializers
 from rest_framework_recursive.fields import RecursiveField
 
-from .models import Todo, TodoAnother, TodoTree, TodoYetAnother
+from .models import Pack, Todo, TodoAnother, TodoTree, TodoYetAnother
 
 
 class TodoSerializer(serializers.ModelSerializer):
@@ -41,10 +41,11 @@ class TodoYetAnotherSerializer(serializers.ModelSerializer):
 
 class TodoTreeSerializer(serializers.ModelSerializer):
     children = serializers.ListField(child=RecursiveField(), source='children.all')
+    many_children = RecursiveField(many=True, source='children')
 
     class Meta:
         model = TodoTree
-        fields = ('id', 'title', 'children')
+        fields = ('id', 'title', 'children', 'many_children')
 
 
 class TodoRecursiveSerializer(serializers.ModelSerializer):
@@ -56,3 +57,14 @@ class TodoRecursiveSerializer(serializers.ModelSerializer):
     class Meta:
         model = TodoTree
         fields = ('id', 'title', 'parent', 'parent_id')
+
+
+class HarvestSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Pack
+        fields = (
+            'size_code',
+        )
+        read_only_fields = (
+            'size_code',
+        )

testproj/todo/urls.py

@@ -9,6 +9,7 @@ router.register(r'another', views.TodoAnotherViewSet)
 router.register(r'yetanother', views.TodoYetAnotherViewSet)
 router.register(r'tree', views.TodoTreeView)
 router.register(r'recursive', views.TodoRecursiveView)
+router.register(r'harvest', views.HarvestViewSet)
 
 urlpatterns = router.urls
 

testproj/todo/views.py

@@ -1,11 +1,13 @@
-from rest_framework import viewsets
+from rest_framework import mixins, permissions, viewsets
+from rest_framework.authentication import TokenAuthentication
 from rest_framework.generics import RetrieveAPIView
 
 from drf_yasg.utils import swagger_auto_schema
 
-from .models import Todo, TodoAnother, TodoTree, TodoYetAnother
+from .models import Pack, Todo, TodoAnother, TodoTree, TodoYetAnother
 from .serializer import (
-    TodoAnotherSerializer, TodoRecursiveSerializer, TodoSerializer, TodoTreeSerializer, TodoYetAnotherSerializer
+    HarvestSerializer, TodoAnotherSerializer, TodoRecursiveSerializer, TodoSerializer, TodoTreeSerializer,
+    TodoYetAnotherSerializer
 )
 
 
@@ -75,3 +77,16 @@ class TodoRecursiveView(viewsets.ModelViewSet):
     @swagger_auto_schema(responses={200: TodoRecursiveSerializer(many=True)})
     def list(self, request, *args, **kwargs):
         return super(TodoRecursiveView, self).list(request, *args, **kwargs)
+
+
+class HarvestViewSet(mixins.ListModelMixin,
+                     mixins.UpdateModelMixin,
+                     viewsets.GenericViewSet):
+
+    queryset = Pack.objects.all()
+    serializer_class = HarvestSerializer
+    permission_classes = [permissions.IsAuthenticated]
+    authentication_classes = [TokenAuthentication]
+
+    def perform_update(self, serializer):
+        pass

testproj/users/migrations/0001_create_admin_user.py

@@ -0,0 +1,38 @@
+# Generated by Django 2.1.3 on 2018-12-19 08:07
+import sys
+
+from django.conf import settings
+from django.contrib.auth.hashers import make_password
+from django.db import migrations, IntegrityError, transaction
+
+
+def add_default_user(apps, schema_editor):
+    username = 'admin'
+    email = 'admin@admin.admin'
+    password = 'passwordadmin'
+    User = apps.get_model(settings.AUTH_USER_MODEL)
+
+    try:
+        with transaction.atomic():
+            admin = User(
+                username=username,
+                email=email,
+                password=make_password(password),
+                is_superuser=True,
+                is_staff=True
+            )
+            admin.save()
+    except IntegrityError:
+        sys.stdout.write(" User '%s <%s>' already exists..." % (username, email))
+    else:
+        sys.stdout.write(" Created superuser '%s <%s>' with password '%s'!" % (username, email, password))
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.RunPython(add_default_user)
+    ]

testproj/users/migrations/0002_setup_oauth2_apps.py

@@ -0,0 +1,39 @@
+# Generated by Django 2.1.3 on 2018-12-19 07:57
+from django.conf import settings
+from django.db import migrations
+
+
+def add_oauth_apps(apps, schema_editor):
+    # We can't import the Person model directly as it may be a newer
+    # version than this migration expects. We use the historical version.
+    User = apps.get_model(settings.AUTH_USER_MODEL)
+    Application = apps.get_model('oauth2_provider', 'application')
+
+    user = User.objects.get(username='admin')
+
+    oauth2_apps = [
+        {
+            "user": user,
+            "client_type": "public",
+            "authorization_grant_type": "password",
+            "client_id": settings.OAUTH2_CLIENT_ID,
+            "client_secret": settings.OAUTH2_CLIENT_SECRET,
+            "redirect_uris": settings.OAUTH2_REDIRECT_URL,
+            "name": settings.OAUTH2_APP_NAME
+        }
+    ]
+
+    for app in oauth2_apps:
+        Application.objects.get_or_create(client_id=app['client_id'], defaults=app)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('oauth2_provider', '0006_auto_20171214_2232'),
+        ('users', '0001_create_admin_user'),
+    ]
+
+    operations = [
+        migrations.RunPython(add_oauth_apps)
+    ]

testproj/users/serializers.py

@@ -1,3 +1,5 @@
+import sys
+
 from django.contrib.auth.models import User
 from rest_framework import serializers
 
@@ -6,7 +8,10 @@ from snippets.models import Snippet
 
 try:
     import typing  # noqa: F401
+    if sys.version_info >= (3, 4):
         from .method_serializers_with_typing import MethodFieldExampleSerializer
+    else:
+        from .method_serializers_without_typing import MethodFieldExampleSerializer
 except ImportError:
     from .method_serializers_without_typing import MethodFieldExampleSerializer
 

testproj/users/views.py

@@ -13,7 +13,11 @@ from users.serializers import UserListQuerySerializer, UserSerializerrr
 class UserList(APIView):
     """UserList cbv classdoc"""
 
-    @swagger_auto_schema(query_serializer=UserListQuerySerializer, responses={200: UserSerializerrr(many=True)})
+    @swagger_auto_schema(
+        query_serializer=UserListQuerySerializer,
+        responses={200: UserSerializerrr(many=True)},
+        tags=['Users'],
+    )
     def get(self, request):
         queryset = User.objects.all()
         serializer = UserSerializerrr(queryset, many=True)
@@ -28,7 +32,8 @@ class UserList(APIView):
                 'username': openapi.Schema(type=openapi.TYPE_STRING)
             },
         ),
-        security=[]
+        security=[],
+        tags=['Users'],
     )
     def post(self, request):
         serializer = UserSerializerrr(request.data)
@@ -36,17 +41,19 @@ class UserList(APIView):
         serializer.save()
         return Response(serializer.data, status=status.HTTP_201_CREATED)
 
-    @swagger_auto_schema(operation_id="users_dummy", operation_description="dummy operation")
+    @swagger_auto_schema(operation_id="users_dummy", operation_description="dummy operation", tags=['Users'])
     def patch(self, request):
         pass
 
 
-@swagger_auto_schema(method='put', request_body=UserSerializerrr)
+@swagger_auto_schema(method='put', request_body=UserSerializerrr, tags=['Users'])
 @swagger_auto_schema(methods=['get'], manual_parameters=[
     openapi.Parameter('test', openapi.IN_QUERY, "test manual param", type=openapi.TYPE_BOOLEAN),
+    openapi.Parameter('test_array', openapi.IN_QUERY, "test query array arg", type=openapi.TYPE_ARRAY,
+                      items=openapi.Items(type=openapi.TYPE_STRING), required=True, collection_format='multi'),
 ], responses={
     200: openapi.Response('response description', UserSerializerrr),
-})
+}, tags=['Users'])
 @api_view(['GET', 'PUT'])
 def user_detail(request, pk):
     """user_detail fbv docstring"""

tests/conftest.py

@@ -22,8 +22,7 @@ def mock_schema_request(db):
     from rest_framework.test import force_authenticate
 
     factory = APIRequestFactory()
-    user = User.objects.create_user(username='admin', is_staff=True, is_superuser=True)
-
+    user = User.objects.get(username='admin')
     request = factory.get('/swagger.json')
     force_authenticate(request, user=user)
     request = APIView().initialize_request(request)
@@ -56,12 +55,17 @@ def swagger_dict(swagger, codec_json):
 
 
 @pytest.fixture
-def validate_schema(db):
+def validate_schema():
     def validate_schema(swagger):
+        try:
             from flex.core import parse as validate_flex
-        from swagger_spec_validator.validator20 import validate_spec as validate_ssv
 
             validate_flex(copy.deepcopy(swagger))
+        except ImportError:
+            pass
+
+        from swagger_spec_validator.validator20 import validate_spec as validate_ssv
+
         validate_ssv(copy.deepcopy(swagger))
 
     return validate_schema

tests/reference.yaml

@@ -1,11 +1,14 @@
 swagger: '2.0'
 info:
   title: Snippets API
-  description: "This is a demo project for the [drf-yasg](https://github.com/axnsan12/drf-yasg)\
-    \ Django Rest Framework library.\n\nThe `swagger-ui` view can be found [here](/cached/swagger).\
-    \  \nThe `ReDoc` view can be found [here](/cached/redoc).  \nThe swagger YAML\
-    \ document can be found [here](/cached/swagger.yaml).  \n\nYou can log in using\
-    \ the pre-existing `admin` user with password `passwordadmin`."
+  description: |-
+    This is a demo project for the [drf-yasg](https://github.com/axnsan12/drf-yasg) Django Rest Framework library.
+
+    The `swagger-ui` view can be found [here](/cached/swagger).
+    The `ReDoc` view can be found [here](/cached/redoc).
+    The swagger YAML document can be found [here](/cached/swagger.yaml).
+
+    You can log in using the pre-existing `admin` user with password `passwordadmin`.
   termsOfService: https://www.google.com/policies/terms/
   contact:
     email: contact@snippets.local
@@ -27,6 +30,13 @@ securityDefinitions:
     in: header
     name: Authorization
     type: apiKey
+  OAuth2 password:
+    flow: password
+    scopes:
+      read: Read everything.
+      write: Write everything,
+    tokenUrl: /o/token/
+    type: oauth2
   Query:
     in: query
     name: auth
@@ -34,6 +44,7 @@ securityDefinitions:
 security:
   - Basic: []
   - Bearer: []
+  - OAuth2 password: []
   - Query: []
 paths:
   /articles/:
@@ -75,9 +86,11 @@ paths:
               next:
                 type: string
                 format: uri
+                x-nullable: true
               previous:
                 type: string
                 format: uri
+                x-nullable: true
               results:
                 type: array
                 items:
@@ -239,6 +252,21 @@ paths:
         - multipart/form-data
       tags:
         - articles
+    delete:
+      operationId: articles_image_delete
+      description: image method docstring
+      parameters:
+        - name: delete_form_param
+          in: formData
+          description: this should not crash (form parameter on DELETE method)
+          type: integer
+      responses:
+        '204':
+          description: ''
+      consumes:
+        - multipart/form-data
+      tags:
+        - articles
     parameters:
       - name: slug
         in: path
@@ -251,7 +279,10 @@ paths:
     get:
       operationId: people_list
       description: ''
-      parameters: []
+      parameters:
+        - name: unknown_paginator
+          in: query
+          type: string
       responses:
         '200':
           description: ''
@@ -415,6 +446,46 @@ paths:
       tags:
         - snippets
     parameters: []
+  /snippets/views/{snippet_pk}/:
+    get:
+      operationId: snippetsViewsRead
+      description: SnippetViewerList classdoc
+      parameters:
+        - name: page
+          in: query
+          description: A page number within the paginated result set.
+          required: false
+          type: integer
+      responses:
+        '200':
+          description: ''
+          schema:
+            required:
+              - count
+              - results
+            type: object
+            properties:
+              count:
+                type: integer
+              next:
+                type: string
+                format: uri
+                x-nullable: true
+              previous:
+                type: string
+                format: uri
+                x-nullable: true
+              results:
+                type: array
+                items:
+                  $ref: '#/definitions/SnippetViewer'
+      tags:
+        - snippets
+    parameters:
+      - name: snippet_pk
+        in: path
+        required: true
+        type: string
   /snippets/{id}/:
     get:
       operationId: snippetsRead
@@ -468,10 +539,6 @@ paths:
           description: path parameter override
           required: true
           type: integer
-        - name: delete_form_param
-          in: formData
-          description: this should not crash (form parameter on DELETE method)
-          type: integer
       responses:
         '204':
           description: this should not crash (response object with no schema)
@@ -531,6 +598,60 @@ paths:
         description: A unique integer value identifying this todo another.
         required: true
         type: integer
+  /todo/harvest/:
+    get:
+      operationId: todo_harvest_list
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Harvest'
+      tags:
+        - todo
+    parameters: []
+  /todo/harvest/{id}/:
+    put:
+      operationId: todo_harvest_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Harvest'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Harvest'
+      tags:
+        - todo
+    patch:
+      operationId: todo_harvest_partial_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Harvest'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Harvest'
+      tags:
+        - todo
+    parameters:
+      - name: id
+        in: path
+        description: A unique integer value identifying this pack.
+        required: true
+        type: integer
   /todo/recursive/:
     get:
       operationId: todo_recursive_list
@@ -761,7 +882,7 @@ paths:
             items:
               $ref: '#/definitions/UserSerializerrr'
       tags:
-        - users
+        - Users
     post:
       operationId: users_create
       description: apiview post description override
@@ -787,7 +908,7 @@ paths:
               username:
                 type: string
       tags:
-        - users
+        - Users
       security: []
     patch:
       operationId: users_dummy
@@ -797,7 +918,7 @@ paths:
         '200':
           description: ''
       tags:
-        - users
+        - Users
     parameters: []
   /users/{id}/:
     get:
@@ -808,13 +929,21 @@ paths:
           in: query
           description: test manual param
           type: boolean
+        - name: test_array
+          in: query
+          description: test query array arg
+          required: true
+          type: array
+          items:
+            type: string
+          collectionFormat: multi
       responses:
         '200':
           description: response description
           schema:
             $ref: '#/definitions/UserSerializerrr'
       tags:
-        - users
+        - Users
     put:
       operationId: users_update
       description: user_detail fbv docstring
@@ -830,7 +959,7 @@ paths:
           schema:
             $ref: '#/definitions/UserSerializerrr'
       tags:
-        - users
+        - Users
     parameters:
       - name: id
         in: path
@@ -873,6 +1002,11 @@ definitions:
         type: string
         format: date-time
         readOnly: true
+      read_only_nullable:
+        type: string
+        readOnly: true
+        minLength: 1
+        x-nullable: true
       references:
         description: this is a really bad example
         type: object
@@ -917,6 +1051,10 @@ definitions:
       - image_styles
     type: object
     properties:
+      image_id:
+        type: string
+        format: uuid
+        readOnly: true
       what_am_i_doing:
         description: test
         type: string
@@ -978,7 +1116,7 @@ definitions:
     type: object
     properties:
       projectName:
-        title: Project name
+        title: project name custom title
         description: Name of the project
         type: string
         minLength: 1
@@ -990,6 +1128,7 @@ definitions:
   Snippet:
     required:
       - code
+      - tags
       - language
     type: object
     properties:
@@ -1024,6 +1163,13 @@ definitions:
         title: Code
         type: string
         minLength: 1
+      tags:
+        type: array
+        items:
+          type: string
+          minLength: 2
+        maxItems: 15
+        minItems: 3
       linenos:
         title: Linenos
         type: boolean
@@ -1036,480 +1182,26 @@ definitions:
             description: The name of the programming language
             type: string
             enum:
-              - abap
-              - abnf
-              - ada
-              - adl
-              - agda
-              - aheui
-              - ahk
-              - alloy
-              - ampl
-              - antlr
-              - antlr-as
-              - antlr-cpp
-              - antlr-csharp
-              - antlr-java
-              - antlr-objc
-              - antlr-perl
-              - antlr-python
-              - antlr-ruby
-              - apacheconf
-              - apl
-              - applescript
-              - arduino
-              - as
-              - as3
-              - aspectj
-              - aspx-cs
-              - aspx-vb
-              - asy
-              - at
-              - autoit
-              - awk
-              - basemake
-              - bash
-              - bat
-              - bbcode
-              - bc
-              - befunge
-              - bib
-              - blitzbasic
-              - blitzmax
-              - bnf
-              - boo
-              - boogie
-              - brainfuck
-              - bro
-              - bst
-              - bugs
-              - c
-              - c-objdump
-              - ca65
-              - cadl
-              - camkes
-              - capdl
-              - capnp
-              - cbmbas
-              - ceylon
-              - cfc
-              - cfengine3
-              - cfm
-              - cfs
-              - chai
-              - chapel
-              - cheetah
-              - cirru
-              - clay
-              - clean
-              - clojure
-              - clojurescript
-              - cmake
-              - cobol
-              - cobolfree
-              - coffee-script
-              - common-lisp
-              - componentpascal
-              - console
-              - control
-              - coq
               - cpp
-              - cpp-objdump
-              - cpsa
-              - cr
-              - crmsh
-              - croc
-              - cryptol
-              - csharp
-              - csound
-              - csound-document
-              - csound-score
-              - css
-              - css+django
-              - css+erb
-              - css+genshitext
-              - css+lasso
-              - css+mako
-              - css+mozpreproc
-              - css+myghty
-              - css+php
-              - css+smarty
-              - cucumber
-              - cuda
-              - cypher
-              - cython
-              - d
-              - d-objdump
-              - dart
-              - delphi
-              - dg
-              - diff
-              - django
-              - docker
-              - doscon
-              - dpatch
-              - dtd
-              - duel
-              - dylan
-              - dylan-console
-              - dylan-lid
-              - earl-grey
-              - easytrieve
-              - ebnf
-              - ec
-              - ecl
-              - eiffel
-              - elixir
-              - elm
-              - emacs
-              - erb
-              - erl
-              - erlang
-              - evoque
-              - extempore
-              - ezhil
-              - factor
-              - fan
-              - fancy
-              - felix
-              - fennel
-              - fish
-              - flatline
-              - forth
-              - fortran
-              - fortranfixed
-              - foxpro
-              - fsharp
-              - gap
-              - gas
-              - genshi
-              - genshitext
-              - glsl
-              - gnuplot
-              - go
-              - golo
-              - gooddata-cl
-              - gosu
-              - groff
-              - groovy
-              - gst
-              - haml
-              - handlebars
-              - haskell
-              - haxeml
-              - hexdump
-              - hlsl
-              - hsail
-              - html
-              - html+cheetah
-              - html+django
-              - html+evoque
-              - html+genshi
-              - html+handlebars
-              - html+lasso
-              - html+mako
-              - html+myghty
-              - html+ng2
-              - html+php
-              - html+smarty
-              - html+twig
-              - html+velocity
-              - http
-              - hx
-              - hybris
-              - hylang
-              - i6t
-              - idl
-              - idris
-              - iex
-              - igor
-              - inform6
-              - inform7
-              - ini
-              - io
-              - ioke
-              - irc
-              - isabelle
-              - j
-              - jags
-              - jasmin
-              - java
-              - javascript+mozpreproc
-              - jcl
-              - jlcon
               - js
-              - js+cheetah
-              - js+django
-              - js+erb
-              - js+genshitext
-              - js+lasso
-              - js+mako
-              - js+myghty
-              - js+php
-              - js+smarty
-              - jsgf
-              - json
-              - json-object
-              - jsonld
-              - jsp
-              - julia
-              - juttle
-              - kal
-              - kconfig
-              - koka
-              - kotlin
-              - lagda
-              - lasso
-              - lcry
-              - lean
-              - less
-              - lhs
-              - lidr
-              - lighty
-              - limbo
-              - liquid
-              - live-script
-              - llvm
-              - logos
-              - logtalk
-              - lsl
-              - lua
-              - make
-              - mako
-              - maql
-              - mask
-              - mason
-              - mathematica
-              - matlab
-              - matlabsession
-              - md
-              - minid
-              - modelica
-              - modula2
-              - monkey
-              - monte
-              - moocode
-              - moon
-              - mozhashpreproc
-              - mozpercentpreproc
-              - mql
-              - mscgen
-              - mupad
-              - mxml
-              - myghty
-              - mysql
-              - nasm
-              - ncl
-              - nemerle
-              - nesc
-              - newlisp
-              - newspeak
-              - ng2
-              - nginx
-              - nim
-              - nit
-              - nixos
-              - nsis
-              - numpy
-              - nusmv
-              - objdump
-              - objdump-nasm
-              - objective-c
-              - objective-c++
-              - objective-j
-              - ocaml
-              - octave
-              - odin
-              - ooc
-              - opa
-              - openedge
-              - pacmanconf
-              - pan
-              - parasail
-              - pawn
-              - perl
-              - perl6
-              - php
-              - pig
-              - pike
-              - pkgconfig
-              - plpgsql
-              - postgresql
-              - postscript
-              - pot
-              - pov
-              - powershell
-              - praat
-              - prolog
-              - properties
-              - protobuf
-              - ps1con
-              - psql
-              - pug
-              - puppet
-              - py3tb
-              - pycon
-              - pypylog
-              - pytb
               - python
-              - python3
-              - qbasic
-              - qml
-              - qvto
-              - racket
-              - ragel
-              - ragel-c
-              - ragel-cpp
-              - ragel-d
-              - ragel-em
-              - ragel-java
-              - ragel-objc
-              - ragel-ruby
-              - raw
-              - rb
-              - rbcon
-              - rconsole
-              - rd
-              - rebol
-              - red
-              - redcode
-              - registry
-              - resource
-              - rexx
-              - rhtml
-              - rnc
-              - roboconf-graph
-              - roboconf-instances
-              - robotframework
-              - rql
-              - rsl
-              - rst
-              - rts
-              - rust
-              - sas
-              - sass
-              - sc
-              - scala
-              - scaml
-              - scheme
-              - scilab
-              - scss
-              - shen
-              - silver
-              - slim
-              - smali
-              - smalltalk
-              - smarty
-              - sml
-              - snobol
-              - snowball
-              - sourceslist
-              - sp
-              - sparql
-              - spec
-              - splus
-              - sql
-              - sqlite3
-              - squidconf
-              - ssp
-              - stan
-              - stata
-              - swift
-              - swig
-              - systemverilog
-              - tads3
-              - tap
-              - tasm
-              - tcl
-              - tcsh
-              - tcshcon
-              - tea
-              - termcap
-              - terminfo
-              - terraform
-              - tex
-              - text
-              - thrift
-              - todotxt
-              - trac-wiki
-              - treetop
-              - ts
-              - tsql
-              - turtle
-              - twig
-              - typoscript
-              - typoscriptcssdata
-              - typoscripthtmldata
-              - urbiscript
-              - vala
-              - vb.net
-              - vcl
-              - vclsnippets
-              - vctreestatus
-              - velocity
-              - verilog
-              - vgl
-              - vhdl
-              - vim
-              - wdiff
-              - whiley
-              - x10
-              - xml
-              - xml+cheetah
-              - xml+django
-              - xml+erb
-              - xml+evoque
-              - xml+lasso
-              - xml+mako
-              - xml+myghty
-              - xml+php
-              - xml+smarty
-              - xml+velocity
-              - xorg.conf
-              - xquery
-              - xslt
-              - xtend
-              - xul+mozpreproc
-              - yaml
-              - yaml+jinja
-              - zephir
             default: python
+          readOnlyNullable:
+            title: Read only nullable
+            type: string
+            readOnly: true
+            minLength: 1
+            x-nullable: true
       styles:
         type: array
         items:
           type: string
           enum:
-            - abap
-            - algol
-            - algol_nu
-            - arduino
-            - autumn
-            - borland
-            - bw
-            - colorful
-            - default
-            - emacs
-            - friendly
-            - fruity
-            - igor
-            - lovelace
-            - manni
             - monokai
-            - murphy
-            - native
-            - paraiso-dark
-            - paraiso-light
-            - pastie
-            - perldoc
-            - rainbow_dash
-            - rrt
-            - tango
-            - trac
+            - solarized-dark
             - vim
-            - vs
-            - xcode
         default:
-          - friendly
+          - solarized-dark
       lines:
         type: array
         items:
@@ -1520,6 +1212,7 @@ definitions:
         items:
           $ref: '#/definitions/Project'
         readOnly: true
+        maxItems: 100
       difficultyFactor:
         title: Difficulty factor
         description: this is here just to test FloatField
@@ -1537,6 +1230,22 @@ definitions:
         format: decimal
         default: 0.0
         minimum: 0.0
+  SnippetViewer:
+    required:
+      - snippet
+      - viewer
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      snippet:
+        title: Snippet
+        type: integer
+      viewer:
+        title: Viewer
+        type: integer
   Todo:
     required:
       - title
@@ -1560,6 +1269,17 @@ definitions:
         minLength: 1
       todo:
         $ref: '#/definitions/Todo'
+  Harvest:
+    type: object
+    properties:
+      size_code:
+        title: Size code
+        type: string
+        enum:
+          - '50'
+          - '100'
+          - '200'
+        readOnly: true
   TodoRecursive:
     required:
       - title
@@ -1584,6 +1304,7 @@ definitions:
     required:
       - title
       - children
+      - many_children
     type: object
     properties:
       id:
@@ -1599,6 +1320,10 @@ definitions:
         type: array
         items:
           $ref: '#/definitions/TodoTree'
+      many_children:
+        type: array
+        items:
+          $ref: '#/definitions/TodoTree'
   TodoYetAnother:
     required:
       - title
@@ -1780,7 +1505,9 @@ definitions:
         readOnly: true
       help_text_example_3:
         title: Help text example 3
-        description: "\n        docstring is set so should appear in swagger as fallback\n\
-          \        :return:\n        "
+        description: |2
+
+          docstring is set so should appear in swagger as fallback
+          :return:
         type: integer
         readOnly: true

tests/test_form_parameters.py

@@ -0,0 +1,44 @@
+import pytest
+from django.conf.urls import url
+from django.utils.decorators import method_decorator
+from rest_framework.authtoken.views import ObtainAuthToken
+from rest_framework.settings import api_settings
+
+from drf_yasg import openapi
+from drf_yasg.errors import SwaggerGenerationError
+from drf_yasg.generators import OpenAPISchemaGenerator
+from drf_yasg.utils import swagger_auto_schema
+
+
+def test_no_form_parameters_with_non_form_parsers():
+    # see https://github.com/axnsan12/drf-yasg/issues/270
+    # test that manual form parameters for views that haven't set
+    # all their parsers classes to form parsers are not allowed
+    # even when the request body is empty
+
+    @method_decorator(name='post', decorator=swagger_auto_schema(
+        operation_description="Logins a user and returns a token",
+        manual_parameters=[
+            openapi.Parameter(
+                "username",
+                openapi.IN_FORM,
+                required=True,
+                type=openapi.TYPE_STRING,
+                description="Valid username or email for authentication"
+            ),
+        ]
+    ))
+    class CustomObtainAuthToken(ObtainAuthToken):
+        throttle_classes = api_settings.DEFAULT_THROTTLE_CLASSES
+
+    urlpatterns = [
+        url(r'token/$', CustomObtainAuthToken.as_view()),
+    ]
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title="Test generator", default_version="v1"),
+        patterns=urlpatterns
+    )
+
+    with pytest.raises(SwaggerGenerationError):
+        generator.get_schema(None, True)

tests/test_get_basic_type_info_from_hint.py

@@ -0,0 +1,43 @@
+import uuid
+
+import pytest
+
+from drf_yasg import openapi
+from drf_yasg.inspectors.field import get_basic_type_info_from_hint
+
+try:
+    import typing
+    from typing import Dict, List, Union, Optional, Set
+except ImportError:
+    typing = None
+
+if typing:
+    @pytest.mark.parametrize('hint_class, expected_swagger_type_info', [
+        (int, {'type': openapi.TYPE_INTEGER, 'format': None}),
+        (str, {'type': openapi.TYPE_STRING, 'format': None}),
+        (bool, {'type': openapi.TYPE_BOOLEAN, 'format': None}),
+        (dict, {'type': openapi.TYPE_OBJECT, 'format': None}),
+        (Dict[int, int], {'type': openapi.TYPE_OBJECT, 'format': None}),
+        (uuid.UUID, {'type': openapi.TYPE_STRING, 'format': openapi.FORMAT_UUID}),
+        (List[int], {'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_INTEGER)}),
+        (List[str], {'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_STRING)}),
+        (List[bool], {'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_BOOLEAN)}),
+        (Set[int], {'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_INTEGER)}),
+        (Optional[bool], {'type': openapi.TYPE_BOOLEAN, 'format': None, 'x-nullable': True}),
+        (Optional[List[int]], {
+            'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_INTEGER), 'x-nullable': True
+        }),
+        (Union[List[int], type(None)], {
+            'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_INTEGER), 'x-nullable': True
+        }),
+        # Following cases are not 100% correct, but it should work somehow and not crash.
+        (Union[int, float], None),
+        (List, {'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_STRING)}),
+        ('SomeType', None),
+        (type('SomeType', (object,), {}), None),
+        (None, None),
+        (6, None),
+    ])
+    def test_get_basic_type_info_from_hint(hint_class, expected_swagger_type_info):
+        type_info = get_basic_type_info_from_hint(hint_class)
+        assert type_info == expected_swagger_type_info

tests/test_management.py

@@ -6,7 +6,6 @@ import tempfile
 from collections import OrderedDict
 
 import pytest
-from django.contrib.auth.models import User
 
 from drf_yasg import openapi
 from drf_yasg.codecs import yaml_sane_load
@@ -14,8 +13,6 @@ from drf_yasg.generators import OpenAPISchemaGenerator
 
 
 def test_reference_schema(call_generate_swagger, db, reference_schema):
-    User.objects.create_superuser('admin', 'admin@admin.admin', 'blabla')
-
     output = call_generate_swagger(format='yaml', api_url='http://test.local:8002/', user='admin')
     output_schema = yaml_sane_load(output)
     assert output_schema == reference_schema

tests/test_referenceresolver.py

@@ -5,7 +5,7 @@ from drf_yasg.openapi import ReferenceResolver
 
 def test_basic():
     scopes = ['s1', 's2']
-    rr = ReferenceResolver(*scopes)
+    rr = ReferenceResolver(*scopes, force_init=True)
     assert scopes == rr.scopes == list(rr.keys()) == list(rr)
     rr.set('o1', 1, scope='s1')
     assert rr.has('o1', scope='s1')
@@ -25,7 +25,7 @@ def test_basic():
 
 def test_scoped():
     scopes = ['s1', 's2']
-    rr = ReferenceResolver(*scopes)
+    rr = ReferenceResolver(*scopes, force_init=True)
     r1 = rr.with_scope('s1')
     r2 = rr.with_scope('s2')
     with pytest.raises(AssertionError):

tests/test_schema_generator.py

@@ -1,8 +1,13 @@
 import json
+import sys
 from collections import OrderedDict
 
 import pytest
 from django.conf.urls import url
+from django.contrib.postgres import fields as postgres_fields
+from django.db import models
+from django.utils.inspect import get_func_args
+from django_fake_model import models as fake_models
 from rest_framework import routers, serializers, viewsets
 from rest_framework.decorators import api_view
 from rest_framework.response import Response
@@ -13,6 +18,11 @@ from drf_yasg.errors import SwaggerGenerationError
 from drf_yasg.generators import OpenAPISchemaGenerator
 from drf_yasg.utils import swagger_auto_schema
 
+try:
+    import typing
+except ImportError:
+    typing = None
+
 
 def test_schema_is_valid(swagger, codec_yaml):
     codec_yaml.encode(swagger)
@@ -86,6 +96,14 @@ def test_securiy_requirements(swagger_settings, mock_schema_request):
     assert swagger['security'] == []
 
 
+def _basename_or_base_name(basename):
+    # freaking DRF... TODO: remove when dropping support for DRF 3.8
+    if 'basename' in get_func_args(routers.BaseRouter.register):
+        return {'basename': basename}
+    else:
+        return {'base_name': basename}
+
+
 def test_replaced_serializer():
     class DetailSerializer(serializers.Serializer):
         detail = serializers.CharField()
@@ -99,7 +117,7 @@ def test_replaced_serializer():
             return Response(serializer.data)
 
     router = routers.DefaultRouter()
-    router.register(r'details', DetailViewSet, base_name='details')
+    router.register(r'details', DetailViewSet, **_basename_or_base_name('details'))
 
     generator = OpenAPISchemaGenerator(
         info=openapi.Info(title="Test generator", default_version="v1"),
@@ -146,7 +164,8 @@ def test_url_order():
     assert swagger['paths']['/test/']['get']['description'] == 'description override'
 
     # get_endpoints only includes one endpoint
-    assert len(generator.get_endpoints(None)['/test/'][1]) == 1
+    endpoints = generator.get_endpoints(None)
+    assert len(endpoints['/test/'][1]) == 1
 
 
 try:
@@ -172,7 +191,7 @@ def test_action_mapping():
             pass
 
     router = routers.DefaultRouter()
-    router.register(r'action', ActionViewSet, base_name='action')
+    router.register(r'action', ActionViewSet, **_basename_or_base_name('action'))
 
     generator = OpenAPISchemaGenerator(
         info=openapi.Info(title="Test generator", default_version="v1"),
@@ -190,3 +209,146 @@ def test_action_mapping():
         assert action_ops['post']['description'] == 'mapping docstring post'
         assert action_ops['get']['description'] == 'mapping docstring get/delete'
         assert action_ops['delete']['description'] == 'mapping docstring get/delete'
+
+
+@pytest.mark.parametrize('choices, expected_type', [
+    (['A', 'B'], openapi.TYPE_STRING),
+    ([u'A', u'B'], openapi.TYPE_STRING),
+    ([123, 456], openapi.TYPE_INTEGER),
+    ([1.2, 3.4], openapi.TYPE_NUMBER),
+    (['A', 456], openapi.TYPE_STRING)
+])
+def test_choice_field(choices, expected_type):
+    class DetailSerializer(serializers.Serializer):
+        detail = serializers.ChoiceField(choices)
+
+    class DetailViewSet(viewsets.ViewSet):
+        @swagger_auto_schema(responses={200: openapi.Response("OK", DetailSerializer)})
+        def retrieve(self, request, pk=None):
+            return Response({'detail': None})
+
+    router = routers.DefaultRouter()
+    router.register(r'details', DetailViewSet, **_basename_or_base_name('details'))
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title="Test generator", default_version="v1"),
+        patterns=router.urls
+    )
+
+    swagger = generator.get_schema(None, True)
+    property_schema = swagger['definitions']['Detail']['properties']['detail']
+
+    assert property_schema == openapi.Schema(title='Detail', type=expected_type, enum=choices)
+
+
+@pytest.mark.parametrize('choices, field, expected_type', [
+    ([1, 2, 3], models.IntegerField, openapi.TYPE_INTEGER),
+    (["A", "B"], models.CharField, openapi.TYPE_STRING),
+])
+def test_nested_choice_in_array_field(choices, field, expected_type):
+
+    # Create a model class on the fly to avoid warnings about using the several
+    # model class name several times
+    model_class = type(
+        "%sModel" % field.__name__,
+        (fake_models.FakeModel,),
+        {
+            "array": postgres_fields.ArrayField(
+                field(choices=((i, "choice %s" % i) for i in choices))
+            ),
+            "__module__": "test_models",
+        }
+    )
+
+    class ArraySerializer(serializers.ModelSerializer):
+        class Meta:
+            model = model_class
+            fields = ("array",)
+
+    class ArrayViewSet(viewsets.ModelViewSet):
+        serializer_class = ArraySerializer
+
+    router = routers.DefaultRouter()
+    router.register(r'arrays', ArrayViewSet, **_basename_or_base_name('arrays'))
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title='Test array model generator', default_version='v1'),
+        patterns=router.urls
+    )
+
+    swagger = generator.get_schema(None, True)
+    property_schema = swagger['definitions']['Array']['properties']['array']['items']
+    assert property_schema == openapi.Schema(title='Array', type=expected_type, enum=choices)
+
+
+def test_json_field():
+    class TestJSONFieldSerializer(serializers.Serializer):
+        json = serializers.JSONField()
+
+    class JSONViewSet(viewsets.ModelViewSet):
+        serializer_class = TestJSONFieldSerializer
+
+    router = routers.DefaultRouter()
+    router.register(r'jsons', JSONViewSet, **_basename_or_base_name('jsons'))
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title='Test json field generator', default_version='v1'),
+        patterns=router.urls
+    )
+
+    swagger = generator.get_schema(None, True)
+    property_schema = swagger["definitions"]["TestJSONField"]["properties"]["json"]
+    assert property_schema == openapi.Schema(title='Json', type=openapi.TYPE_OBJECT)
+
+
+@pytest.mark.parametrize('py_type, expected_type', [
+    (str, openapi.TYPE_STRING),
+    (int, openapi.TYPE_INTEGER),
+    (float, openapi.TYPE_NUMBER),
+    (bool, openapi.TYPE_BOOLEAN),
+])
+@pytest.mark.skipif(typing is None or sys.version_info.major < 3, reason="typing not supported")
+def test_optional_return_type(py_type, expected_type):
+
+    class OptionalMethodSerializer(serializers.Serializer):
+        x = serializers.SerializerMethodField()
+
+        def get_x(self, instance):
+            pass
+
+        # Add the type annotation here in order to avoid a SyntaxError in py27
+        get_x.__annotations__["return"] = typing.Optional[py_type]
+
+    class OptionalMethodViewSet(viewsets.ViewSet):
+        @swagger_auto_schema(responses={200: openapi.Response("OK", OptionalMethodSerializer)})
+        def retrieve(self, request, pk=None):
+            return Response({'optional': None})
+
+    router = routers.DefaultRouter()
+    router.register(r'optional', OptionalMethodViewSet, **_basename_or_base_name('optional'))
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title='Test optional parameter', default_version='v1'),
+        patterns=router.urls
+    )
+    swagger = generator.get_schema(None, True)
+    property_schema = swagger["definitions"]["OptionalMethod"]["properties"]["x"]
+    assert property_schema == openapi.Schema(title='X', type=expected_type, readOnly=True)
+
+
+EXPECTED_DESCRIPTION = """\
+  description: |-
+    This is a demo project for the [drf-yasg](https://github.com/axnsan12/drf-yasg) Django Rest Framework library.
+
+    The `swagger-ui` view can be found [here](/cached/swagger).
+    The `ReDoc` view can be found [here](/cached/redoc).
+    The swagger YAML document can be found [here](/cached/swagger.yaml).
+
+    You can log in using the pre-existing `admin` user with password `passwordadmin`.
+"""
+
+
+def test_multiline_strings(call_generate_swagger):
+    output = call_generate_swagger(format='yaml')
+    print("|\n|".join(output.splitlines()[:20]))
+    assert EXPECTED_DESCRIPTION in output

tests/urlconfs/login_test_urls.py

@@ -1,11 +1,13 @@
 from django.conf.urls import url
 
+from testproj.urls import required_urlpatterns
+
 
 def dummy(request):
     pass
 
 
-urlpatterns = [
+urlpatterns = required_urlpatterns + [
     url(r'^test/login$', dummy, name='login'),
     url(r'^test/logout$', dummy, name='logout'),
 ]

tests/urlconfs/ns_version1.py

@@ -3,6 +3,7 @@ from rest_framework import generics, versioning
 
 from snippets.models import Snippet
 from snippets.serializers import SnippetSerializer
+from testproj.urls import required_urlpatterns
 
 
 class SnippetList(generics.ListCreateAPIView):
@@ -21,6 +22,6 @@ class SnippetList(generics.ListCreateAPIView):
 
 app_name = 'test_ns_versioning'
 
-urlpatterns = [
+urlpatterns = required_urlpatterns + [
     url(r"^$", SnippetList.as_view())
 ]

tests/urlconfs/ns_version2.py

@@ -2,6 +2,7 @@ from django.conf.urls import url
 from rest_framework import fields
 
 from snippets.serializers import SnippetSerializer
+from testproj.urls import required_urlpatterns
 
 from .ns_version1 import SnippetList as SnippetListV1
 
@@ -19,6 +20,6 @@ class SnippetListV2(SnippetListV1):
 
 app_name = '2.0'
 
-urlpatterns = [
+urlpatterns = required_urlpatterns + [
     url(r"^$", SnippetListV2.as_view())
 ]

tests/urlconfs/ns_versioning.py

@@ -1,7 +1,7 @@
 from django.conf.urls import include, url
 from rest_framework import versioning
 
-from testproj.urls import SchemaView
+from testproj.urls import SchemaView, required_urlpatterns
 
 from . import ns_version1, ns_version2
 
@@ -17,7 +17,7 @@ schema_patterns = [
 ]
 
 
-urlpatterns = [
+urlpatterns = required_urlpatterns + [
     url(VERSION_PREFIX_NS + r"v1.0/snippets/", include(ns_version1, namespace='1.0')),
     url(VERSION_PREFIX_NS + r"v2.0/snippets/", include(ns_version2)),
     url(VERSION_PREFIX_NS + r'v1.0/', include((schema_patterns, '1.0'))),

tests/urlconfs/url_versioning.py

@@ -3,7 +3,7 @@ from rest_framework import fields, generics, versioning
 
 from snippets.models import Snippet
 from snippets.serializers import SnippetSerializer
-from testproj.urls import SchemaView
+from testproj.urls import SchemaView, required_urlpatterns
 
 
 class SnippetSerializerV2(SnippetSerializer):
@@ -42,7 +42,7 @@ class VersionedSchemaView(SchemaView):
     versioning_class = versioning.URLPathVersioning
 
 
-urlpatterns = [
+urlpatterns = required_urlpatterns + [
     url(VERSION_PREFIX_URL + r"snippets/$", SnippetList.as_view()),
     url(VERSION_PREFIX_URL + r'swagger(?P<format>.json|.yaml)$', VersionedSchemaView.without_ui(), name='vschema-json'),
 ]

tox.ini

@@ -1,31 +1,54 @@
 [tox]
+minversion = 3.3.0
+isolated_build = true
+isolated_build_env = .package
+
 # https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
 envlist =
-    py{27,34,35,36}-django111-drf{37,38},
-    py{34,35,36,37}-django20-drf{37,38},
-    py{35,36,37}-django21-drf{37,38},
+    py36-django{111,22}-drf{38,39},
+    py37-django22-drf{38,39,310,311},
+    py38-django{22,3}-drf{310,311},
     djmaster, lint, docs
+skip_missing_interpreters = true
+
+[testenv:.package]
+# no additional dependencies besides PEP 517
+deps =
 
 [testenv]
 deps =
     django111: Django>=1.11,<2.0
-    django20: Django>=2.0,<2.1
+    django111: django-oauth-toolkit>=1.1.0,<1.2.0
+
     django21: Django>=2.1,<2.2
+    django21: django-oauth-toolkit>=1.2.0
 
-    drf37: djangorestframework>=3.7.7,<3.8
-    drf38: djangorestframework>=3.8.0,<3.9
+    django22: Django>=2.2,<2.3
+    django22: django-oauth-toolkit>=1.2.0
 
-    # test with the latest build of django-rest-framework to get early warning of compatibility issues
-    djmaster: https://github.com/encode/django-rest-framework/archive/master.tar.gz
+    django3: Django>=2.2,<2.3
+    django3: django-oauth-toolkit>=1.2.0
+
+    drf38: djangorestframework>=3.8,<3.9
+    drf39: djangorestframework>=3.9,<3.10
+    drf310: djangorestframework>=3.10,<3.11
+    drf311: djangorestframework>=3.11,<3.12
+
+    typing: typing>=3.6.6
+
+    # test with the latest builds of Django and django-rest-framework
+    # to get early warning of compatibility issues
     djmaster: https://github.com/django/django/archive/master.tar.gz
+    djmaster: https://github.com/ottoyiu/django-cors-headers/archive/master.tar.gz
+    djmaster: https://github.com/encode/django-rest-framework/archive/master.tar.gz
+    djmaster: django-oauth-toolkit>=1.2.0
 
     # other dependencies
-    -rrequirements/setup.txt
     -r requirements/validation.txt
     -r requirements/test.txt
 
 commands =
-    pytest --cov --cov-config .coveragerc --cov-append --cov-report="" {posargs}
+    pytest -n 2 --cov --cov-config .coveragerc --cov-append --cov-report="" {posargs}
 
 [testenv:lint]
 skip_install = true
@@ -36,16 +59,15 @@ commands =
 
 [testenv:docs]
 deps =
-    -rrequirements/setup.txt
     -r requirements/docs.txt
 commands =
-    python setup.py check --restructuredtext --metadata --strict
+    twine check .tox/dist/*
     sphinx-build -WnEa -b html docs docs/_build/html
 
 [pytest]
 DJANGO_SETTINGS_MODULE = testproj.settings.local
 python_paths = testproj
-addopts = -n 2 --ignore=node_modules
+addopts = --ignore=node_modules
 
 [flake8]
 max-line-length = 120
@@ -65,6 +87,6 @@ known_standard_library =
     types,warnings
 known_third_party =
     coreapi,coreschema,datadiff,dj_database_url,django,django_filters,djangorestframework_camel_case,
-    rest_framework_recursive,flex,gunicorn,inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm,
-    swagger_spec_validator,uritemplate,user_agents,whitenoise
+    rest_framework_recursive,flex,gunicorn,inflection,pytest,rest_framework,ruamel,setuptools_scm,
+    swagger_spec_validator,uritemplate,user_agents,whitenoise,oauth2_provider,packaging
 known_first_party = drf_yasg,testproj,articles,people,snippets,todo,users,urlconfs