Rename swagger_serializer_method parameter and update docs

Closes #158.

.travis.yml

@@ -1,28 +1,34 @@
 language: python
-cache: pip
-
+sudo: false
 python:
- - '3.4'
- - '3.5'
- - '3.6'
+  - '2.7'
+  - '3.4'
+  - '3.5'
+  - '3.6'
 
-env:
- - DRF=3.7
- - DRF=3.8
+cache:
+  directories:
+  - $HOME/.cache/pip
+  - .tox
+before_cache:
+  - rm -f $HOME/.cache/pip/log/debug.log
+  - rm -fr .tox/log/ .tox/*/log/ .tox/*/tmp/ .tox/dist .tox/*/lib/*/site-packages/drf_yasg*
 
 jobs:
   include:
-    - stage: test
-      python: '2.7'
-      env: DRF=3.7
+    - # 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: DRF=master
-    -
+      env: TOXENV=djmaster
+    - # readthedocs uses python 3.5 for building
       python: '3.5'
       env: TOXENV=docs
     -
-      python: '2.7'
+      python: '3.6'
       env: TOXENV=lint
 
     - stage: publish
@@ -40,7 +46,7 @@ jobs:
 
   allow_failures:
     - env: TOXENV=lint
-    - env: DRF=master
+    - env: TOXENV=djmaster
 
   fast_finish: true
 
@@ -49,20 +55,16 @@ install:
 
 before_script:
  - coverage erase
- - |
-  [[ -z "$TOXENV" && -z "$PYPI_DEPLOY" ]] && REPORT_COVERAGE="yes" || REPORT_COVERAGE="no";
-  echo "Reporting coverage: ${REPORT_COVERAGE}"
- - |
-  [[ -z "$TOXENV" && ! -z "$DRF" && "$DRF" != "master" ]] && USE_DETOX="yes" || USE_DETOX="no";
-  echo "Using detox: ${USE_DETOX}"
 
 script:
- - 'if [[ "$USE_DETOX" == "yes" ]]; then detox; else tox; fi'
+ - tox
 
 after_success:
- - coverage combine
- - 'if [[ "$REPORT_COVERAGE" == "yes" ]]; then coverage report; fi'
- - 'if [[ "$REPORT_COVERAGE" == "yes" ]]; then codecov; fi'
+  - |
+    if [[ -z "$TOXENV" && -z "$PYPI_DEPLOY" ]]; then
+      chmod +x coverage.sh
+      ./coverage.sh
+    fi
 
 branches:
   only:

CONTRIBUTING.rst

@@ -35,8 +35,8 @@ You want to contribute some code? Great! Here are a few steps to get you started
 
       $ virtualenv venv
       $ source venv/bin/activate
-      (venv) $ pip install -e .[validation]
-      (venv) $ pip install -r requirements/dev.txt
+      (venv) $ pip install -U -e .[validation]
+      (venv) $ pip install -U -r requirements/dev.txt
 
 #. **Make your changes and check them against the test project**
 

README.rst

@@ -11,9 +11,9 @@ Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framewor
 
 Compatible with
 
-- **Django Rest Framework**: 3.7.7, 3.8.x
-- **Django**: 1.11.x, 2.0.x
-- **Python**: 2.7, 3.4, 3.5, 3.6
+- **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
 
 Resources:
 
@@ -85,14 +85,14 @@ The preferred instalation method is directly from pypi:
 
 .. code:: console
 
-   pip install drf-yasg
+   pip install -U drf-yasg
 
 Additionally, if you want to use the built-in validation mechanisms (see `4. Validation`_), you need to install
 some extra requirements:
 
 .. code:: console
 
-   pip install drf-yasg[validation]
+   pip install -U drf-yasg[validation]
 
 .. _readme-quickstart:
 
@@ -294,7 +294,7 @@ 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) $ pip install -r requirements.txt
+   (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
@@ -315,8 +315,8 @@ From here on, the terms “OpenAPI” and “Swagger” are used interchangeably
 Swagger in Django Rest Framework
 ================================
 
-Since Django Rest 3.7, there is now `built in support <http://www.django-rest-framework.org/api-guide/schemas/>`__ for
-automatic OpenAPI 2.0 schema generation. However, this generation is based on the `coreapi <http://www.coreapi.org/>`__
+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:
 
@@ -329,18 +329,15 @@ In short this makes the generated schema unusable for code generation, and medio
 Other libraries
 ===============
 
-There are currently two decent Swagger schema generators that I could
-find for django-rest-framework:
+There are currently two decent Swagger schema generators that I could find for django-rest-framework:
 
 * `django-rest-swagger <https://github.com/marcgibbons/django-rest-swagger>`__
 * `drf-openapi <https://github.com/limdauto/drf_openapi>`__
 
-Out of the two, ``django-rest-swagger`` is just a wrapper around DRF 3.7 schema generation with an added UI, and
-thus presents the same problems. ``drf-openapi`` is a bit more involved and implements some custom handling for response
-schemas, but ultimately still falls short in code generation because the responses are plain of lacking support for
-named schemas.
-
-Both projects are also currently unmantained.
+``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

coverage.sh

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

docs/changelog.rst

@@ -4,9 +4,31 @@ Changelog
 
 
 **********
-**1.9.2**
+**1.10.0**
 **********
 
+*Release date: Aug 08, 2018*
+
+- **ADDED:** added ``EXCLUDED_MEDIA_TYPES`` setting for controlling ``produces`` MIME type filtering (:issue:`158`)
+- **ADDED:** added support for ``SerializerMethodField``, via the ``swagger_serializer_method`` decorator for the
+  method field, and support for Python 3.5 style type hinting of the method field return type
+  (:issue:`137`, :pr:`175`, :pr:`179`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.SerializerMethodFieldInspector``
+  to your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.18.0
+- **IMPROVED:** added support for Python 3.7 and Django 2.1 (:pr:`176`)
+- **IMPROVED:** ``swagger_schema_fields`` will now also work on serializer ``Field``\ s (:issue:`167`)
+- **IMPROVED:** ``ref_name`` collisions will now log a warning message (:issue:`156`)
+- **IMPROVED:** added ``operation_summary`` and ``deprecated`` arguments to ``swagger_auto_schema``
+  (:issue:`149`, :issue:`173`)
+- **FIXED:** made ``swagger_auto_schema`` work with DRF 3.9 ``@action`` mappings (:issue:`177`)
+
+*********
+**1.9.2**
+*********
+
 *Release date: Aug 03, 2018*
 
 - **IMPROVED:** updated ``swagger-ui`` to version 3.17.6
@@ -24,7 +46,7 @@ Changelog
 
 - **IMPROVED:** added a ``swagger_fake_view`` marker to more easily detect mock views in view methods;
   ``getattr(self, 'swagger_fake_view', False)`` inside a view method like ``get_serializer_class`` will tell you if the
-  view instnace is being used for swagger schema introspection (:issue:`154`)
+  view instance is being used for swagger schema introspection (:issue:`154`)
 - **IMPROVED:** updated ``swagger-ui`` to version 3.17.1
 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.25
 - **FIXED:** fixed wrong handling of duplicate urls in urlconf (:pr:`155`)
@@ -39,7 +61,7 @@ Changelog
 - **ADDED:** added ``DEFAULT_GENERATOR_CLASS`` setting and ``--generator-class`` argument to the ``generate_swagger``
   management command (:issue:`140`)
 - **FIXED:** fixed wrongly required ``'count'`` response field on ``CursorPagination`` (:issue:`141`)
-- **FIXED:** fixed some cases where ``swagger_extra_fields`` would not be handlded (:pr:`142`)
+- **FIXED:** fixed some cases where ``swagger_schema_fields`` would not be handlded (:pr:`142`)
 - **FIXED:** fixed crash when encountering ``coreapi.Fields``\ s without a ``schema`` (:issue:`143`)
 
 *********

docs/custom_spec.rst

@@ -155,6 +155,57 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
    replacing/decorating methods on the base class itself.
 
 
+*********************************
+Support for SerializerMethodField
+*********************************
+
+Schema generation of ``serializers.SerializerMethodField`` is supported in two ways:
+
+1) The :func:`swagger_serializer_method <.swagger_serializer_method>` decorator for the use case where the serializer
+   method is using a serializer. e.g.:
+
+   .. code-block:: python
+
+      from drf_yasg.utils import swagger_serializer_method
+
+      class OtherStuffSerializer(serializers.Serializer):
+          foo = serializers.CharField()
+
+      class ParentSerializer(serializers.Serializer):
+          other_stuff = serializers.SerializerMethodField()
+
+          @swagger_serializer_method(serializer_or_field=OtherStuffSerializer)
+          def get_other_stuff(self, obj):
+              return OtherStuffSerializer().data
+
+
+   Note that the ``serializer_or_field`` parameter can accept either a subclass or an instance of ``serializers.Field``.
+
+
+2) For simple cases where the method is returning one of the supported types, `Python 3 type hinting`_ of the
+   serializer method return value can be used. e.g.:
+
+   .. code-block:: python
+
+      class SomeSerializer(serializers.Serializer):
+          some_number = serializers.SerializerMethodField()
+
+          def get_some_number(self, obj) -> float:
+              return 1.0
+
+   When return type hinting is not supported, the equivalent ``serializers.Field`` subclass can be used with
+   :func:`swagger_serializer_method <.swagger_serializer_method>`:
+
+   .. code-block:: python
+
+      class SomeSerializer(serializers.Serializer):
+          some_number = serializers.SerializerMethodField()
+
+          @swagger_serializer_method(serializer_or_field=serializers.FloatField)
+          def get_some_number(self, obj):
+              return 1.0
+
+
 ********************************
 Serializer ``Meta`` nested class
 ********************************
@@ -333,3 +384,6 @@ A second example, of a :class:`~.inspectors.FieldInspector` that removes the ``t
 
    Another caveat that stems from this is that any serializer named "``NestedSerializer``" will be forced inline
    unless it has a ``ref_name`` set explicitly.
+
+
+.. _Python 3 type hinting: https://docs.python.org/3/library/typing.html

docs/settings.rst

@@ -76,6 +76,7 @@ to this list.
 :class:`'drf_yasg.inspectors.DictFieldInspector' <.inspectors.DictFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.HiddenFieldInspector' <.inspectors.HiddenFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.RecursiveFieldInspector' <.inspectors.RecursiveFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.SerializerMethodFieldInspector' <.inspectors.SerializerMethodFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.SimpleFieldInspector' <.inspectors.SimpleFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.StringDefaultFieldInspector' <.inspectors.StringDefaultFieldInspector>`, |br| \
 ``]``
@@ -104,6 +105,14 @@ Paginator inspectors given to :func:`@swagger_auto_schema <.swagger_auto_schema>
 Swagger document attributes
 ===========================
 
+EXCLUDED_MEDIA_TYPES
+--------------------
+
+A list of keywords for excluding MIME types from ``Operation.produces``. Any MIME type string which includes one of
+the substrings in this list will be prevented from appearing in a ``produces`` array in the Swagger document.
+
+**Default**: :python:`['html']`
+
 .. _default-swagger-settings:
 
 DEFAULT_INFO

package-lock.json

@@ -501,9 +501,9 @@
       }
     },
     "swagger-ui-dist": {
-      "version": "3.17.6",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.17.6.tgz",
-      "integrity": "sha1-37Y7uHZdOKNzjPWUZYad4W3Uczk="
+      "version": "3.18.0",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.18.0.tgz",
+      "integrity": "sha512-AwFwmd9pf4XJb/IwLvpZ6Bl6wDhjidwjgBiqGv3/kXHp1hbVWi5ZKGSwKjdJ9att6MDJFhgp0+Dvd/Zqb7uySA=="
     },
     "tiny-emitter": {
       "version": "2.0.2",

package.json

@@ -2,7 +2,7 @@
   "name": "drf-yasg",
   "dependencies": {
     "redoc": "^2.0.0-alpha.32",
-    "swagger-ui-dist": "^3.17.6"
+    "swagger-ui-dist": "^3.18.0"
   },
   "repository": {
     "type": "git",

requirements.txt

@@ -1,2 +1,3 @@
+-r requirements/setup.txt
 .[validation]
 -r requirements/heroku.txt

requirements/dev.txt

@@ -1,6 +1,4 @@
-# requirements for local development to be installed via pip install -r requirements/dev.txt
+# requirements for local development to be installed via pip install -U -r requirements/dev.txt
 -r tox.txt
 -r test.txt
 -r lint.txt
-
-tox-battery>=0.5

requirements/docs.txt

@@ -4,5 +4,5 @@ sphinx_rtd_theme>=0.2.4
 Pillow>=4.3.0
 readme_renderer>=17.2
 
-Django>=2.0,<2.1
+Django>=2.0
 djangorestframework_camel_case>=0.2.0

requirements/setup.txt

@@ -1,4 +1,3 @@
 # needed to build the package setup_requires in setup.py
 
-# do not unpin this (see setup.py)
-setuptools_scm==1.15.6
+setuptools-scm>=3.0.6

requirements/test.txt

@@ -1,5 +1,5 @@
 # requirements for running the tests via pytest
-pytest>=2.9
+pytest>=2.9,<3.7  # <3.7 because of incompatible pluggy requirement
 pytest-pythonpath>=0.7.1
 pytest-cov>=2.5.1
 pytest-xdist>=1.22.0

requirements/tox.txt

@@ -1,5 +1,5 @@
 # requirements for building and running tox
-tox>=2.9.1,<3.0.0
-detox>=0.11
+tox>=3.1.2
+tox-battery>=0.5
 
 -r setup.txt

runtime.txt

@@ -1 +1 @@
-python-3.6.4
+python-3.6.6

setup.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-import distutils.core
+from __future__ import print_function
+
 import io
 import os
-import random
-import string
 import sys
 from setuptools import find_packages, setup
 
@@ -22,88 +21,67 @@ requirements_setup = read_req('setup.txt')
 requirements_validation = read_req('validation.txt')
 
 
-def _install_setup_requires(attrs):
-    # copied from setuptools
-    dist = distutils.core.Distribution(dict(
-        (k, v) for k, v in attrs.items()
-        if k in ('dependency_links', 'setup_requires')
-    ))
-    # Honor setup.cfg's options.
-    dist.parse_config_files(ignore_option_errors=True)
-    if dist.setup_requires:
-        dist.fetch_build_eggs(dist.setup_requires)
+def drf_yasg_setup(**kwargs):
+    setup(
+        name='drf-yasg',
+        packages=find_packages('src'),
+        package_dir={'': 'src'},
+        include_package_data=True,
+        install_requires=requirements,
+        setup_requires=requirements_setup,
+        extras_require={
+            'validation': requirements_validation,
+        },
+        license='BSD License',
+        description='Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.',
+        long_description=description,
+        url='https://github.com/axnsan12/drf-yasg',
+        author='Cristi V.',
+        author_email='cristi@cvjd.me',
+        keywords='drf django django-rest-framework schema swagger openapi codegen swagger-codegen '
+                 'documentation drf-yasg django-rest-swagger drf-openapi',
+        python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
+        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',
+            'Topic :: Documentation',
+            'Topic :: Software Development :: Code Generators',
+        ],
+        **kwargs
+    )
 
 
 try:
-    # try to install setuptools_scm before setuptools does it, otherwise our monkey patch below will come too early
-    # (setuptools_scm adds find_files hooks into setuptools on install)
-    _install_setup_requires({'setup_requires': requirements_setup})
-except Exception:
-    pass
-
-if 'sdist' in sys.argv:
-    try:
-        # see https://github.com/pypa/setuptools_scm/issues/190, setuptools_scm includes ALL versioned files from
-        # the git repo into the sdist by default, and there is no easy way to provide an opt-out;
-        # this hack is ugly but does the job; because this is not really a documented interface of the module,
-        # the setuptools_scm version should remain pinned to ensure it keeps working
-        import setuptools_scm.integration
-
-        setuptools_scm.integration.find_files = lambda _: []
-    except ImportError:
-        pass
-
-try:
-    # this is a workaround for being able to install the package from source without working from a git checkout
-    # it is needed for building succesfully on Heroku
-    from setuptools_scm import get_version
-
-    version = get_version()
-    version_kwargs = {'use_scm_version': True}
-except LookupError:
-    if 'sdist' in sys.argv or 'bdist_wheel' in sys.argv:
+    drf_yasg_setup(use_scm_version=True)
+except 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
 
-    rnd = ''.join(random.choice(string.ascii_lowercase + string.digits) for _ in range(16))
-    version_kwargs = {'version': '0.0.0.dummy+' + rnd}
+    if 'setuptools-scm' in str(e):
+        import time
 
-setup(
-    name='drf-yasg',
-    packages=find_packages('src'),
-    package_dir={'': 'src'},
-    include_package_data=True,
-    install_requires=requirements,
-    setup_requires=requirements_setup,
-    extras_require={
-        'validation': requirements_validation,
-    },
-    license='BSD License',
-    description='Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.',
-    long_description=description,
-    url='https://github.com/axnsan12/drf-yasg',
-    author='Cristi V.',
-    author_email='cristi@cvjd.me',
-    keywords='drf django django-rest-framework schema swagger openapi codegen swagger-codegen '
-             'documentation drf-yasg django-rest-swagger drf-openapi',
-    python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
-    classifiers=[
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: BSD License',
-        'Development Status :: 4 - Beta',
-        'Operating System :: OS Independent',
-        'Environment :: Web Environment',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 2',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.4',
-        'Programming Language :: Python :: 3.5',
-        'Programming Language :: Python :: 3.6',
-        'Framework :: Django',
-        'Framework :: Django :: 1.11',
-        'Framework :: Django :: 2.0',
-        'Topic :: Documentation',
-        'Topic :: Software Development :: Code Generators',
-    ],
-    **version_kwargs
-)
+        timestamp_ms = int(time.time() * 1000)
+        timestamp_str = hex(timestamp_ms)[2:].zfill(16)
+        dummy_version = '0.0.0rc0+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)
+    else:
+        raise

src/drf_yasg/app_settings.py

@@ -14,6 +14,7 @@ SWAGGER_DEFAULTS = {
         'drf_yasg.inspectors.DictFieldInspector',
         'drf_yasg.inspectors.HiddenFieldInspector',
         'drf_yasg.inspectors.RelatedFieldInspector',
+        'drf_yasg.inspectors.SerializerMethodFieldInspector',
         'drf_yasg.inspectors.SimpleFieldInspector',
         'drf_yasg.inspectors.StringDefaultFieldInspector',
     ],
@@ -25,6 +26,8 @@ SWAGGER_DEFAULTS = {
         'drf_yasg.inspectors.CoreAPICompatInspector',
     ],
 
+    'EXCLUDED_MEDIA_TYPES': ['html'],
+
     'DEFAULT_INFO': None,
     'DEFAULT_API_URL': None,
 

src/drf_yasg/codecs.py

@@ -5,7 +5,6 @@ import json
 from collections import OrderedDict
 
 from coreapi.compat import force_bytes
-from django.utils.safestring import SafeData, SafeText
 from ruamel import yaml
 
 from . import openapi

src/drf_yasg/generators.py

@@ -31,8 +31,7 @@ class EndpointEnumerator(_EndpointEnumerator):
 
     def get_path_from_regex(self, path_regex):
         if path_regex.endswith(')'):
-            logger.warning("url pattern does not end in $ ('%s') - unexpected things might happen",
-                           path_regex)
+            logger.warning("url pattern does not end in $ ('%s') - unexpected things might happen", path_regex)
         return self.unescape_path(super(EndpointEnumerator, self).get_path_from_regex(path_regex))
 
     def should_include_endpoint(self, path, callback, app_name='', namespace='', url_name=None):

src/drf_yasg/inspectors/__init__.py

@@ -5,12 +5,12 @@ from .base import (
 from .field import (
     CamelCaseJSONFilter, ChoiceFieldInspector, DictFieldInspector, FileFieldInspector, HiddenFieldInspector,
     InlineSerializerInspector, RecursiveFieldInspector, ReferencingSerializerInspector, RelatedFieldInspector,
-    SimpleFieldInspector, StringDefaultFieldInspector
+    SerializerMethodFieldInspector, SimpleFieldInspector, StringDefaultFieldInspector
 )
 from .query import CoreAPICompatInspector, DjangoRestResponsePagination
 from .view import SwaggerAutoSchema
 
-# these settings must be accesed only after definig/importing all the classes in this module to avoid ImportErrors
+# these settings must be accessed only after defining/importing all the classes in this module to avoid ImportErrors
 ViewInspector.field_inspectors = swagger_settings.DEFAULT_FIELD_INSPECTORS
 ViewInspector.filter_inspectors = swagger_settings.DEFAULT_FILTER_INSPECTORS
 ViewInspector.paginator_inspectors = swagger_settings.DEFAULT_PAGINATOR_INSPECTORS
@@ -25,7 +25,7 @@ __all__ = [
     # field inspectors
     'InlineSerializerInspector', 'RecursiveFieldInspector', 'ReferencingSerializerInspector', 'RelatedFieldInspector',
     'SimpleFieldInspector', 'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector',
-    'StringDefaultFieldInspector', 'CamelCaseJSONFilter', 'HiddenFieldInspector',
+    'StringDefaultFieldInspector', 'CamelCaseJSONFilter', 'HiddenFieldInspector', 'SerializerMethodFieldInspector',
 
     # view inspectors
     'SwaggerAutoSchema',

src/drf_yasg/inspectors/base.py

@@ -2,10 +2,9 @@ import inspect
 import logging
 
 from rest_framework import serializers
-from rest_framework.utils import encoders, json
 
 from .. import openapi
-from ..utils import decimal_as_float, force_real_str, is_list_view
+from ..utils import force_real_str, get_field_default, is_list_view
 
 #: Sentinel value that inspectors must return to signal that they do not know how to handle an object
 NotHandled = object()
@@ -135,6 +134,19 @@ class FieldInspector(BaseInspector):
         super(FieldInspector, self).__init__(view, path, method, components, request)
         self.field_inspectors = field_inspectors
 
+    def add_manual_fields(self, serializer_or_field, schema):
+        """Set fields from the ``swagger_schem_fields`` attribute on the Meta class. This method is called
+        only for serializers or fields that are converted into ``openapi.Schema`` objects.
+
+        :param serializer_or_field: serializer or field instance
+        :param openapi.Schema schema: the schema object to be modified in-place
+        """
+        meta = getattr(serializer_or_field, 'Meta', None)
+        swagger_schema_fields = getattr(meta, 'swagger_schema_fields', {})
+        if swagger_schema_fields:
+            for attr, val in swagger_schema_fields.items():
+                setattr(schema, attr, val)
+
     def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
         """Convert a drf Serializer or Field instance into a Swagger object.
 
@@ -205,46 +217,29 @@ class FieldInspector(BaseInspector):
                 instance_kwargs['required'] = field.required
 
             if 'default' not in instance_kwargs and swagger_object_type != openapi.Items:
-                default = getattr(field, 'default', serializers.empty)
-                if default is not serializers.empty:
-                    if callable(default):
-                        try:
-                            if hasattr(default, 'set_context'):
-                                default.set_context(field)
-                            default = default()
-                        except Exception:  # pragma: no cover
-                            logger.warning("default for %s is callable but it raised an exception when "
-                                           "called; 'default' field will not be added to schema", field, exc_info=True)
-                            default = None
-
-                    if default is not None:
-                        try:
-                            default = field.to_representation(default)
-                            # JSON roundtrip ensures that the value is valid JSON;
-                            # for example, sets and tuples get transformed into lists
-                            default = json.loads(json.dumps(default, cls=encoders.JSONEncoder))
-                            if decimal_as_float(field):
-                                default = float(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 = None
-
-                    if default is not None:
-                        instance_kwargs['default'] = default
+                default = get_field_default(field)
+                if default not in (None, serializers.empty):
+                    instance_kwargs['default'] = default
 
             if instance_kwargs.get('type', None) != openapi.TYPE_ARRAY:
                 instance_kwargs.setdefault('title', title)
-            instance_kwargs.setdefault('description', description)
+            if description is not None:
+                instance_kwargs.setdefault('description', description)
             instance_kwargs.update(kwargs)
 
             if existing_object is not None:
                 assert isinstance(existing_object, swagger_object_type)
-                for attr, val in sorted(instance_kwargs.items()):
-                    setattr(existing_object, attr, val)
-                return existing_object
+                for key, val in sorted(instance_kwargs.items()):
+                    setattr(existing_object, key, val)
+                result = existing_object
+            else:
+                result = swagger_object_type(**instance_kwargs)
 
-            return swagger_object_type(**instance_kwargs)
+            # Provide an option to add manual paremeters to a schema
+            # for example, to add examples
+            if swagger_object_type == openapi.Schema:
+                self.add_manual_fields(field, result)
+            return result
 
         # arrays in Schema have Schema elements, arrays in Parameter and Items have Items elements
         child_swagger_type = openapi.Schema if swagger_object_type == openapi.Schema else openapi.Items

src/drf_yasg/inspectors/field.py

@@ -1,5 +1,8 @@
+import datetime
+import inspect
 import logging
 import operator
+import uuid
 from collections import OrderedDict
 from decimal import Decimal
 
@@ -10,9 +13,15 @@ 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_ref_name
+from ..utils import decimal_as_float, filter_none, get_serializer_class, get_serializer_ref_name
 from .base import FieldInspector, NotHandled, SerializerInspector
 
+try:
+    # Python>=3.5
+    import typing
+except ImportError:
+    typing = None
+
 logger = logging.getLogger(__name__)
 
 
@@ -22,19 +31,6 @@ class InlineSerializerInspector(SerializerInspector):
     #: whether to output :class:`.Schema` definitions inline or into the ``definitions`` section
     use_definitions = False
 
-    def add_manual_fields(self, serializer, schema):
-        """Set fields from the ``swagger_schem_fields`` attribute on the serializer's Meta class. This method is called
-        only for serializers that are converted into ``openapi.Schema`` objects.
-
-        :param serializer: serializer instance
-        :param openapi.Schema schema: the schema object to be modified in-place
-        """
-        serializer_meta = getattr(serializer, 'Meta', None)
-        swagger_schema_fields = getattr(serializer_meta, 'swagger_schema_fields', {})
-        if swagger_schema_fields:
-            for attr, val in swagger_schema_fields.items():
-                setattr(schema, attr, val)
-
     def get_schema(self, serializer):
         return self.probe_field_inspectors(serializer, openapi.Schema, self.use_definitions)
 
@@ -111,20 +107,23 @@ class InlineSerializerInspector(SerializerInspector):
                 )
                 if not ref_name and 'title' in result:
                     # on an inline model, the title is derived from the field name
-                    # but is visually displayed like the model name, which is confusing
+                    # but is visno coverually displayed like the model name, which is confusing
                     # it is better to just remove title from inline models
                     del result.title
 
-                # Provide an option to add manual paremeters to a schema
-                # for example, to add examples
-                self.add_manual_fields(field, result)
                 return result
 
             if not ref_name or not use_references:
                 return make_schema_definition()
 
             definitions = self.components.with_scope(openapi.SCHEMA_DEFINITIONS)
-            definitions.setdefault(ref_name, make_schema_definition)
+            actual_schema = definitions.setdefault(ref_name, make_schema_definition)
+            actual_serializer = get_serializer_class(getattr(actual_schema, '_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)
+
             return openapi.SchemaRef(definitions, ref_name)
 
         return NotHandled
@@ -409,6 +408,118 @@ def get_basic_type_info(field):
     return result
 
 
+def decimal_return_type():
+    return openapi.TYPE_STRING if rest_framework_settings.COERCE_DECIMAL_TO_STRING else openapi.TYPE_NUMBER
+
+
+raw_type_info = [
+    (bool, (openapi.TYPE_BOOLEAN, None)),
+    (int, (openapi.TYPE_INTEGER, None)),
+    (float, (openapi.TYPE_NUMBER, 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
+
+
+def get_basic_type_info_from_hint(hint_class):
+    """Given a class (eg from a SerializerMethodField's return type hint,
+    return its basic type information - ``type``, ``format``, ``pattern``,
+    and any applicable min/max limit values.
+
+    :param hint_class: the class
+    :return: the extracted attributes as a dictionary, or ``None`` if the field type is not known
+    :rtype: OrderedDict
+    """
+
+    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)
+    ])
+
+    return result
+
+
+class SerializerMethodFieldInspector(FieldInspector):
+    """Provides conversion for SerializerMethodField, optionally using information from the swagger_serializer_method
+    decorator.
+    """
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        if not isinstance(field, serializers.SerializerMethodField):
+            return NotHandled
+
+        method = getattr(field.parent, field.method_name)
+        if method is None:
+            return NotHandled
+
+        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)
+            # 3) method's docstring
+            description = field.help_text
+            if description is None:
+                description = getattr(serializer, 'help_text', None)
+            if description is None:
+                description = method.__doc__
+
+            label = field.label
+            if label is None:
+                label = getattr(serializer, 'label', None)
+
+            if inspect.isclass(serializer):
+                serializer_kwargs = {
+                    "help_text": description,
+                    "label": label,
+                    "read_only": True,
+                }
+
+                serializer = method._swagger_serializer(**serializer_kwargs)
+            else:
+                serializer.help_text = description
+                serializer.label = label
+                serializer.read_only = True
+
+            return self.probe_field_inspectors(serializer, swagger_object_type, use_references, read_only=True)
+        elif typing:
+            # look for Python 3.5+ style type hinting of the return value
+            hint_class = inspect.signature(method).return_annotation
+
+            if not issubclass(hint_class, inspect._empty):
+                type_info = get_basic_type_info_from_hint(hint_class)
+
+                if type_info is not None:
+                    SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type,
+                                                                            use_references, **kwargs)
+                    return SwaggerType(**type_info)
+
+        return NotHandled
+
+
 class SimpleFieldInspector(FieldInspector):
     """Provides conversions for fields which can be described using just ``type``, ``format``, ``pattern``
     and min/max validators.
@@ -569,14 +680,15 @@ except ImportError:  # pragma: no cover
 else:
     class RecursiveFieldInspector(FieldInspector):
         """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+
         def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
             if isinstance(field, RecursiveField) and swagger_object_type == openapi.Schema:
                 assert use_references is True, "Can not create schema for RecursiveField when use_references is False"
 
                 ref_name = get_serializer_ref_name(field.proxied)
-                assert ref_name is not None, "Can not create RecursiveField schema for inline ModelSerializer"
+                assert ref_name is not None, "Can't create RecursiveField schema for inline " + str(type(field.proxied))
 
-                return openapi.SchemaRef(self.components.with_scope(openapi.SCHEMA_DEFINITIONS), ref_name,
-                                         ignore_unresolved=True)
+                definitions = self.components.with_scope(openapi.SCHEMA_DEFINITIONS)
+                return openapi.SchemaRef(definitions, ref_name, ignore_unresolved=True)
 
             return NotHandled

src/drf_yasg/inspectors/view.py

@@ -34,8 +34,10 @@ class SwaggerAutoSchema(ViewInspector):
 
         operation_id = self.get_operation_id(operation_keys)
         description = self.get_description()
+        summary = self.get_summary()
         security = self.get_security()
         assert security is None or isinstance(security, list), "security must be a list of securiy requirement objects"
+        deprecated = self.is_deprecated()
         tags = self.get_tags(operation_keys)
 
         responses = self.get_responses()
@@ -43,12 +45,14 @@ class SwaggerAutoSchema(ViewInspector):
         return openapi.Operation(
             operation_id=operation_id,
             description=force_real_str(description),
+            summary=force_real_str(summary),
             responses=responses,
             parameters=parameters,
             consumes=consumes,
             produces=produces,
             tags=tags,
-            security=security
+            security=security,
+            deprecated=deprecated
         )
 
     def get_request_body_parameters(self, consumes):
@@ -325,6 +329,14 @@ class SwaggerAutoSchema(ViewInspector):
             description = self._sch.get_description(self.path, self.method)
         return description
 
+    def get_summary(self):
+        """Return a summary description for this operation.
+
+        :return: the summary
+        :rtype: str
+        """
+        return self.overrides.get('operation_summary', None)
+
     def get_security(self):
         """Return a list of security requirements for this operation.
 
@@ -335,6 +347,14 @@ class SwaggerAutoSchema(ViewInspector):
         :rtype: list[dict[str,list[str]]]"""
         return self.overrides.get('security', None)
 
+    def is_deprecated(self):
+        """Return ``True`` if this operation is to be marked as deprecated.
+
+        :return: deprecation status
+        :rtype: bool
+        """
+        return self.overrides.get('deprecated', None)
+
     def get_tags(self, operation_keys):
         """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.

src/drf_yasg/openapi.py

@@ -1,3 +1,4 @@
+import logging
 import re
 from collections import OrderedDict
 
@@ -7,6 +8,8 @@ from inflection import camelize
 
 from .utils import filter_none
 
+logger = logging.getLogger(__name__)
+
 TYPE_OBJECT = "object"  #:
 TYPE_STRING = "string"  #:
 TYPE_NUMBER = "number"  #:
@@ -628,8 +631,13 @@ class ReferenceResolver(object):
         ret = self.getdefault(name, None, scope)
         if ret is None:
             ret = maker()
+            value = self.getdefault(name, None, scope)
             assert ret is not None, "maker returned None; referenced objects cannot be None/null"
-            self.set(name, ret, scope)
+            if value is None:
+                self.set(name, ret, scope)
+            elif value != ret:
+                logger.debug("during setdefault, maker for %s inserted a value and returned a different value", name)
+                ret = value
 
         return ret
 

src/drf_yasg/utils.py

@@ -8,8 +8,11 @@ from rest_framework import serializers, status
 from rest_framework.mixins import DestroyModelMixin, RetrieveModelMixin, UpdateModelMixin
 from rest_framework.request import is_form_media_type
 from rest_framework.settings import api_settings as rest_framework_settings
+from rest_framework.utils import encoders, json
 from rest_framework.views import APIView
 
+from drf_yasg.app_settings import swagger_settings
+
 logger = logging.getLogger(__name__)
 
 
@@ -24,9 +27,9 @@ 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, security=None,
-                        responses=None, field_inspectors=None, filter_inspectors=None, paginator_inspectors=None,
-                        **extra_overrides):
+                        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):
     """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
@@ -67,9 +70,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
 
     :param str operation_id: operation ID override; the operation ID must be unique accross the whole API
     :param str operation_description: operation description override
+    :param str operation_summary: operation summary string
     :param list[dict] security: security requirements override; used to specify which authetication mechanism
         is requried to call this API; an empty list marks the endpoint as unauthenticated (i.e. removes all accepted
         authentication schemes), and ``None`` will inherit the top-level secuirty requirements
+    :param bool deprecated: deprecation status for operation
     :param dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: a dict of documented manual responses
         keyed on response status code. If no success (``2xx``) response is given, one will automatically be
         generated from the request body and http method. If any ``2xx`` response is given the automatic response is
@@ -117,19 +122,22 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
             # no overrides to set, no use in doing more work
             return
 
-        # if the method is an @action, it will have a bind_to_methods attribute
+        # if the method is an @action, it will have a bind_to_methods attribute, or a mapping attribute for drf>3.8
         bind_to_methods = getattr(view_method, 'bind_to_methods', [])
+        mapping = getattr(view_method, 'mapping', {})
+        mapping_methods = [mth for mth, name in mapping.items() if name == view_method.__name__]
+        action_http_methods = bind_to_methods + mapping_methods
+
         # if the method is actually a function based view (@api_view), it will have a 'cls' attribute
         view_cls = getattr(view_method, 'cls', None)
-        http_method_names = [m for m in getattr(view_cls, 'http_method_names', []) if hasattr(view_cls, m)]
+        api_view_http_methods = [m for m in getattr(view_cls, 'http_method_names', []) if hasattr(view_cls, m)]
 
-        available_methods = http_method_names + bind_to_methods
+        available_http_methods = api_view_http_methods + action_http_methods
         existing_data = getattr(view_method, '_swagger_auto_schema', {})
 
         _methods = methods
         if methods or method:
-            assert available_methods or http_method_names, "`method` or `methods` can only be specified " \
-                                                           "on @action or @api_view views"
+            assert available_http_methods, "`method` or `methods` can only be specified on @action or @api_view views"
             assert bool(methods) != bool(method), "specify either method or methods"
             assert not isinstance(methods, str), "`methods` expects to receive a list of methods;" \
                                                  " use `method` for a single argument"
@@ -137,20 +145,20 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
                 _methods = [method.lower()]
             else:
                 _methods = [mth.lower() for mth in methods]
-            assert all(mth in available_methods for mth in _methods), "http method not bound to view"
+            assert all(mth in available_http_methods for mth in _methods), "http method not bound to view"
             assert not any(mth in existing_data for mth in _methods), "http method defined multiple times"
 
-        if available_methods:
+        if available_http_methods:
             # action or api_view
-            assert bool(http_method_names) != bool(bind_to_methods), "this should never happen"
+            assert bool(api_view_http_methods) != bool(action_http_methods), "this should never happen"
 
-            if len(available_methods) > 1:
+            if len(available_http_methods) > 1:
                 assert _methods, \
                     "on multi-method api_view, action, detail_route or list_route, you must specify " \
                     "swagger_auto_schema on a per-method basis using one of the `method` or `methods` arguments"
             else:
                 # for a single-method view we assume that single method as the decorator target
-                _methods = _methods or available_methods
+                _methods = _methods or available_http_methods
 
             assert not any(hasattr(getattr(view_cls, mth, None), '_swagger_auto_schema') for mth in _methods), \
                 "swagger_auto_schema applied twice to method"
@@ -170,6 +178,23 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
     return decorator
 
 
+def swagger_serializer_method(serializer_or_field):
+    """
+    Decorates the method of a serializers.SerializerMethodField
+    to hint as to how Swagger should be generated for this field.
+
+    :param serializer_or_field: ``Serializer``/``Field`` class or instance
+    :return:
+    """
+
+    def decorator(serializer_method):
+        # stash the serializer for SerializerMethodFieldInspector to find
+        serializer_method._swagger_serializer = serializer_or_field
+        return serializer_method
+
+    return decorator
+
+
 def is_list_view(path, method, view):
     """Check if the given path/method appears to represent a list view (as opposed to a detail/instance view).
 
@@ -251,6 +276,7 @@ def force_serializer_instance(serializer):
 
     :param serializer: serializer class or instance
     :return: serializer instance
+    :rtype: serializers.BaseSerializer
     """
     if inspect.isclass(serializer):
         assert issubclass(serializer, serializers.BaseSerializer), "Serializer required, not %s" % serializer.__name__
@@ -261,6 +287,26 @@ def force_serializer_instance(serializer):
     return serializer
 
 
+def get_serializer_class(serializer):
+    """Given a ``Serializer`` class or intance, return the ``Serializer`` class. If `serializer` is not a ``Serializer``
+    class or instance, raises an assertion error.
+
+    :param serializer: serializer class or instance, or ``None``
+    :return: serializer class
+    :rtype: type[serializers.BaseSerializer]
+    """
+    if serializer is None:
+        return None
+
+    if inspect.isclass(serializer):
+        assert issubclass(serializer, serializers.BaseSerializer), "Serializer required, not %s" % serializer.__name__
+        return serializer
+
+    assert isinstance(serializer, serializers.BaseSerializer), \
+        "Serializer class or instance required, not %s" % type(serializer).__name__
+    return type(serializer)
+
+
 def get_consumes(parser_classes):
     """Extract ``consumes`` MIME types from a list of parser classes.
 
@@ -284,7 +330,8 @@ def get_produces(renderer_classes):
     :rtype: list[str]
     """
     media_types = [renderer.media_type for renderer in renderer_classes or []]
-    media_types = [encoding for encoding in media_types if 'html' not in encoding]
+    media_types = [encoding for encoding in media_types
+                   if not any(excluded in encoding for excluded in swagger_settings.EXCLUDED_MEDIA_TYPES)]
     return media_types
 
 
@@ -313,7 +360,7 @@ def get_serializer_ref_name(serializer):
     if hasattr(serializer_meta, 'ref_name'):
         ref_name = serializer_meta.ref_name
     elif serializer_name == 'NestedSerializer' and isinstance(serializer, serializers.ModelSerializer):
-        logger.debug("Forcing inline output for ModelSerializer named 'NestedSerializer': " + str(serializer))
+        logger.debug("Forcing inline output for ModelSerializer named 'NestedSerializer':\n" + str(serializer))
         ref_name = None
     else:
         ref_name = serializer_name
@@ -334,3 +381,38 @@ def force_real_str(s, encoding='utf-8', strings_only=False, errors='strict'):
             s = '' + s
 
     return s
+
+
+def get_field_default(field):
+    """
+    Get the default value for a field, converted to a JSON-compatible value while properly handling callables.
+
+    :param field: field instance
+    :return: default value
+    """
+    default = getattr(field, 'default', serializers.empty)
+    if default is not serializers.empty:
+        if callable(default):
+            try:
+                if hasattr(default, 'set_context'):
+                    default.set_context(field)
+                default = default()
+            except Exception:  # pragma: no cover
+                logger.warning("default for %s is callable but it raised an exception when "
+                               "called; 'default' will not be set on schema", field, exc_info=True)
+                default = serializers.empty
+
+        if default is not serializers.empty:
+            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)
+            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

testproj/people/migrations/0002_rename_identity_fields.py

@@ -0,0 +1,28 @@
+# Generated by Django 2.1 on 2018-08-06 13:34
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('people', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='identity',
+            name='lastName',
+            field=models.CharField(help_text="<strong>Here's some HTML!</strong>", max_length=30, null=True),
+        ),
+        migrations.RenameField(
+            model_name='identity',
+            old_name='firstName',
+            new_name='first_name',
+        ),
+        migrations.RenameField(
+            model_name='identity',
+            old_name='lastName',
+            new_name='last_name',
+        ),
+    ]

testproj/people/models.py

@@ -3,8 +3,8 @@ from django.utils.safestring import mark_safe
 
 
 class Identity(models.Model):
-    firstName = models.CharField(max_length=30, null=True)
-    lastName = models.CharField(max_length=30, null=True, help_text=mark_safe("<strong>Here's some HTML!</strong>"))
+    first_name = models.CharField(max_length=30, null=True)
+    last_name = models.CharField(max_length=30, null=True, help_text=mark_safe("<strong>Here's some HTML!</strong>"))
 
 
 class Person(models.Model):

testproj/snippets/serializers.py

@@ -23,12 +23,34 @@ class ExampleProjectSerializer(serializers.Serializer):
         ref_name = 'Project'
 
 
+class UnixTimestampField(serializers.DateTimeField):
+    def to_representation(self, value):
+        """ Return epoch time for a datetime object or ``None``"""
+        from django.utils.dateformat import format
+        try:
+            return int(format(value, 'U'))
+        except (AttributeError, TypeError):
+            return None
+
+    def to_internal_value(self, value):
+        import datetime
+        return datetime.datetime.fromtimestamp(int(value))
+
+    class Meta:
+        swagger_schema_fields = {
+            'format': 'integer',
+            'title': 'Client date time suu',
+            'description': 'Date time in unix timestamp format',
+        }
+
+
 class SnippetSerializer(serializers.Serializer):
     """SnippetSerializer classdoc
 
     create: docstring for create from serializer classdoc
     """
     id = serializers.IntegerField(read_only=True, help_text="id serializer help text")
+    created = UnixTimestampField(read_only=True)
     owner = serializers.PrimaryKeyRelatedField(
         queryset=get_user_model().objects.all(),
         default=serializers.CurrentUserDefault(),

testproj/users/method_serializers_with_typing.py

@@ -0,0 +1,69 @@
+import datetime
+import decimal
+import uuid
+
+from rest_framework import serializers
+
+
+class Unknown(object):
+    pass
+
+
+class MethodFieldExampleSerializer(serializers.Serializer):
+    """
+    Implementation of SerializerMethodField using type hinting for Python >= 3.5
+    """
+
+    hinted_bool = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a bool")
+
+    def get_hinted_bool(self, obj) -> bool:
+        return True
+
+    hinted_int = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be an integer")
+
+    def get_hinted_int(self, obj) -> int:
+        return 1
+
+    hinted_float = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a number")
+
+    def get_hinted_float(self, obj) -> float:
+        return 1.0
+
+    hinted_decimal = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a decimal")
+
+    def get_hinted_decimal(self, obj) -> decimal.Decimal:
+        return decimal.Decimal(1)
+
+    hinted_datetime = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a datetime")
+
+    def get_hinted_datetime(self, obj) -> datetime.datetime:
+        return datetime.datetime.now()
+
+    hinted_date = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a date")
+
+    def get_hinted_date(self, obj) -> datetime.date:
+        return datetime.date.today()
+
+    hinted_uuid = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a uuid")
+
+    def get_hinted_uuid(self, obj) -> uuid.UUID:
+        return uuid.uuid4()
+
+    hinted_unknown = serializers.SerializerMethodField(
+        help_text="type hint is unknown, so is expected to fallback to string")
+
+    def get_hinted_unknown(self, obj) -> Unknown:
+        return Unknown()
+
+    non_hinted_number = serializers.SerializerMethodField(
+        help_text="No hint on the method, so this is expected to fallback to string")
+
+    def get_non_hinted_number(self, obj):
+        return 1.0

testproj/users/method_serializers_without_typing.py

@@ -0,0 +1,82 @@
+import datetime
+import decimal
+import uuid
+
+from rest_framework import serializers
+
+from drf_yasg.utils import swagger_serializer_method
+
+
+class Unknown(object):
+    pass
+
+
+class MethodFieldExampleSerializer(serializers.Serializer):
+    """
+    Fallback implementation of SerializerMethodField type hinting for Python < 3.5
+
+    `->` syntax isn't supported, instead decorate with a serializer that returns the same type
+    a bit of a hack, but it provides a cross-check between hinting and decorator functionality.
+    """
+
+    hinted_bool = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a bool")
+
+    @swagger_serializer_method(serializer_or_field=serializers.BooleanField)
+    def get_hinted_bool(self, obj):
+        return True
+
+    hinted_int = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be an integer")
+
+    @swagger_serializer_method(serializer_or_field=serializers.IntegerField)
+    def get_hinted_int(self, obj):
+        return 1
+
+    hinted_float = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a number")
+
+    @swagger_serializer_method(serializer_or_field=serializers.FloatField)
+    def get_hinted_float(self, obj):
+        return 1.0
+
+    hinted_decimal = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a decimal")
+
+    # note that in this case an instance is required since DecimalField has required arguments
+    @swagger_serializer_method(serializer_or_field=serializers.DecimalField(max_digits=6, decimal_places=4))
+    def get_hinted_decimal(self, obj):
+        return decimal.Decimal(1)
+
+    hinted_datetime = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a datetime")
+
+    @swagger_serializer_method(serializer_or_field=serializers.DateTimeField)
+    def get_hinted_datetime(self, obj):
+        return datetime.datetime.now()
+
+    hinted_date = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a date")
+
+    @swagger_serializer_method(serializer_or_field=serializers.DateField)
+    def get_hinted_date(self, obj):
+        return datetime.date.today()
+
+    hinted_uuid = serializers.SerializerMethodField(
+        help_text="the type hint on the method should determine this to be a uuid")
+
+    @swagger_serializer_method(serializer_or_field=serializers.UUIDField)
+    def get_hinted_uuid(self, obj):
+        return uuid.uuid4()
+
+    hinted_unknown = serializers.SerializerMethodField(
+        help_text="type hint is unknown, so is expected to fallback to string")
+
+    def get_hinted_unknown(self, obj):
+        return Unknown()
+
+    non_hinted_number = serializers.SerializerMethodField(
+        help_text="No hint on the method, so this is expected to fallback to string")
+
+    def get_non_hinted_number(self, obj):
+        return 1.0

testproj/users/serializers.py

@@ -1,8 +1,19 @@
 from django.contrib.auth.models import User
 from rest_framework import serializers
 
+from drf_yasg.utils import swagger_serializer_method
 from snippets.models import Snippet
 
+try:
+    import typing  # noqa: F401
+    from .method_serializers_with_typing import MethodFieldExampleSerializer
+except ImportError:
+    from .method_serializers_without_typing import MethodFieldExampleSerializer
+
+
+class OtherStuffSerializer(serializers.Serializer):
+    foo = serializers.CharField()
+
 
 class UserSerializerrr(serializers.ModelSerializer):
     snippets = serializers.PrimaryKeyRelatedField(many=True, queryset=Snippet.objects.all())
@@ -10,10 +21,61 @@ class UserSerializerrr(serializers.ModelSerializer):
     last_connected_ip = serializers.IPAddressField(help_text="i'm out of ideas", protocol='ipv4', read_only=True)
     last_connected_at = serializers.DateField(help_text="really?", read_only=True)
 
+    other_stuff = serializers.SerializerMethodField(
+        help_text="the decorator should determine the serializer class for this")
+
+    hint_example = MethodFieldExampleSerializer()
+
+    @swagger_serializer_method(serializer_or_field=OtherStuffSerializer)
+    def get_other_stuff(self, obj):
+        """
+        method_field that uses a serializer internally.
+
+        By using the decorator, we can tell drf-yasg how to represent this in Swagger
+        :param obj:
+        :return:
+        """
+        return OtherStuffSerializer().data
+
+    help_text_example_1 = serializers.SerializerMethodField(
+        help_text="help text on field is set, so this should appear in swagger"
+    )
+
+    @swagger_serializer_method(serializer_or_field=serializers.IntegerField(
+        help_text="decorated instance help_text shouldn't appear in swagger because field has priority"))
+    def get_help_text_example_1(self):
+        """
+        method docstring shouldn't appear in swagger because field has priority
+        :return:
+        """
+        return 1
+
+    help_text_example_2 = serializers.SerializerMethodField()
+
+    @swagger_serializer_method(serializer_or_field=serializers.IntegerField(
+        help_text="instance help_text is set, so should appear in swagger"))
+    def get_help_text_example_2(self):
+        """
+        method docstring shouldn't appear in swagger because decorator has priority
+        :return:
+        """
+        return 1
+
+    help_text_example_3 = serializers.SerializerMethodField()
+
+    @swagger_serializer_method(serializer_or_field=serializers.IntegerField())
+    def get_help_text_example_3(self):
+        """
+        docstring is set so should appear in swagger as fallback
+        :return:
+        """
+        return 1
+
     class Meta:
         model = User
         fields = ('id', 'username', 'email', 'articles', 'snippets',
-                  'last_connected_ip', 'last_connected_at', 'article_slugs')
+                  'last_connected_ip', 'last_connected_at', 'article_slugs', 'other_stuff', 'hint_example',
+                  'help_text_example_1', 'help_text_example_2', 'help_text_example_3')
 
 
 class UserListQuerySerializer(serializers.Serializer):

tests/reference.yaml

@@ -898,13 +898,13 @@ definitions:
         title: ID
         type: integer
         readOnly: true
-      firstName:
-        title: FirstName
+      first_name:
+        title: First name
         type: string
         maxLength: 30
         minLength: 1
-      lastName:
-        title: LastName
+      last_name:
+        title: Last name
         description: <strong>Here's some HTML!</strong>
         type: string
         maxLength: 30
@@ -947,6 +947,12 @@ definitions:
         description: id serializer help text
         type: integer
         readOnly: true
+      created:
+        title: Client date time suu
+        type: string
+        format: integer
+        readOnly: true
+        description: Date time in unix timestamp format
       owner:
         title: Owner
         description: The ID of the user that created this snippet; if none is provided,
@@ -1582,11 +1588,77 @@ definitions:
       todo:
         title: child
         todo: null
+  OtherStuff:
+    title: Other stuff
+    description: the decorator should determine the serializer class for this
+    required:
+      - foo
+    type: object
+    properties:
+      foo:
+        title: Foo
+        type: string
+        minLength: 1
+    readOnly: true
+  MethodFieldExample:
+    title: Hint example
+    type: object
+    properties:
+      hinted_bool:
+        title: Hinted bool
+        description: the type hint on the method should determine this to be a bool
+        type: boolean
+        readOnly: true
+      hinted_int:
+        title: Hinted int
+        description: the type hint on the method should determine this to be an integer
+        type: integer
+        readOnly: true
+      hinted_float:
+        title: Hinted float
+        description: the type hint on the method should determine this to be a number
+        type: number
+        readOnly: true
+      hinted_decimal:
+        title: Hinted decimal
+        description: the type hint on the method should determine this to be a decimal
+        type: string
+        format: decimal
+        readOnly: true
+      hinted_datetime:
+        title: Hinted datetime
+        description: the type hint on the method should determine this to be a datetime
+        type: string
+        format: date-time
+        readOnly: true
+      hinted_date:
+        title: Hinted date
+        description: the type hint on the method should determine this to be a date
+        type: string
+        format: date
+        readOnly: true
+      hinted_uuid:
+        title: Hinted uuid
+        description: the type hint on the method should determine this to be a uuid
+        type: string
+        format: uuid
+        readOnly: true
+      hinted_unknown:
+        title: Hinted unknown
+        description: type hint is unknown, so is expected to fallback to string
+        type: string
+        readOnly: true
+      non_hinted_number:
+        title: Non hinted number
+        description: No hint on the method, so this is expected to fallback to string
+        type: string
+        readOnly: true
   UserSerializerrr:
     required:
       - username
       - articles
       - snippets
+      - hint_example
     type: object
     properties:
       id:
@@ -1637,3 +1709,23 @@ definitions:
           pattern: ^[-a-zA-Z0-9_]+$
         readOnly: true
         uniqueItems: true
+      other_stuff:
+        $ref: '#/definitions/OtherStuff'
+      hint_example:
+        $ref: '#/definitions/MethodFieldExample'
+      help_text_example_1:
+        title: Help text example 1
+        description: help text on field is set, so this should appear in swagger
+        type: integer
+        readOnly: true
+      help_text_example_2:
+        title: Help text example 2
+        description: instance help_text is set, so should appear in swagger
+        type: integer
+        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        "
+        type: integer
+        readOnly: true

tests/test_management.py

@@ -1,5 +1,3 @@
-from six import StringIO
-
 import json
 import os
 import random

tests/test_schema_generator.py

@@ -147,3 +147,46 @@ def test_url_order():
 
     # get_endpoints only includes one endpoint
     assert len(generator.get_endpoints(None)['/test/'][1]) == 1
+
+
+try:
+    from rest_framework.decorators import action, MethodMapper
+except ImportError:
+    action = MethodMapper = None
+
+
+@pytest.mark.skipif(not MethodMapper or not action, reason="action.mapping test (djangorestframework>=3.9 required)")
+def test_action_mapping():
+    class ActionViewSet(viewsets.ViewSet):
+        @swagger_auto_schema(method='get', operation_id='mapping_get')
+        @swagger_auto_schema(method='delete', operation_id='mapping_delete')
+        @action(detail=False, methods=['get', 'delete'], url_path='test')
+        def action_main(self, request):
+            """mapping docstring get/delete"""
+            pass
+
+        @swagger_auto_schema(operation_id='mapping_post')
+        @action_main.mapping.post
+        def action_post(self, request):
+            """mapping docstring post"""
+            pass
+
+    router = routers.DefaultRouter()
+    router.register(r'action', ActionViewSet, base_name='action')
+
+    generator = OpenAPISchemaGenerator(
+        info=openapi.Info(title="Test generator", default_version="v1"),
+        version="v2",
+        url='',
+        patterns=router.urls
+    )
+
+    for _ in range(3):
+        swagger = generator.get_schema(None, True)
+        action_ops = swagger['paths']['/test/']
+        methods = ['get', 'post', 'delete']
+        assert all(mth in action_ops for mth in methods)
+        assert all(action_ops[mth]['operationId'] == 'mapping_' + mth for mth in methods)
+        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'

tox.ini

@@ -1,28 +1,29 @@
 [tox]
+# https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
 envlist =
-    py27-django111-drf37,
-    py{34,35,36}-django{111,20}-drf{37,38},
-    py36-django20-drfmaster,
-    lint, docs
-
-[travis:env]
-DRF =
-    3.7: drf37
-    3.8: drf38
-    master: drfmaster
+    py{27,34,35,36}-django111-drf37,
+    py{27,34,35,36}-django111-drf38,
+    py{34,35,36,37}-django20-drf37,
+    py{34,35,36,37}-django20-drf38,
+    py{35,36,37}-django21-drf37,
+    py{35,36,37}-django21-drf38,
+    djmaster, lint, docs
 
 [testenv]
 deps =
     django111: Django>=1.11,<2.0
     django20: Django>=2.0,<2.1
+    django21: Django>=2.1,<2.2
 
     drf37: djangorestframework>=3.7.7,<3.8
     drf38: djangorestframework>=3.8.0,<3.9
 
     # test with the latest build of django-rest-framework to get early warning of compatibility issues
-    drfmaster: https://github.com/encode/django-rest-framework/archive/master.tar.gz
+    djmaster: https://github.com/encode/django-rest-framework/archive/master.tar.gz
+    djmaster: https://github.com/django/django/archive/master.tar.gz
 
     # other dependencies
+    -rrequirements/setup.txt
     -rrequirements/validation.txt
     -rrequirements/test.txt
 
@@ -32,12 +33,14 @@ commands =
 [testenv:lint]
 skip_install = true
 deps =
+    -rrequirements/setup.txt
     -rrequirements/lint.txt
 commands =
     flake8 src/drf_yasg testproj tests setup.py
 
 [testenv:docs]
 deps =
+    -rrequirements/setup.txt
     -rrequirements/docs.txt
 commands =
     python setup.py check --restructuredtext --metadata --strict
@@ -46,7 +49,7 @@ commands =
 [pytest]
 DJANGO_SETTINGS_MODULE = testproj.settings.local
 python_paths = testproj
-addopts = -n 3 --ignore=node_modules
+addopts = -n 2 --ignore=node_modules
 
 [flake8]
 max-line-length = 120
@@ -54,7 +57,7 @@ exclude = **/migrations/*
 ignore = F405
 
 [isort]
-skip = .eggs,.tox,docs,env,venv
+skip = .eggs,.tox,docs,env,venv,node_modules
 skip_glob = **/migrations/*
 not_skip = __init__.py
 atomic = true