Superficial fixes

* add get_serializer_ref_name utility function
* implement RecursiveFieldInspector
* add option to allow non-existing reference in SchemaRef
* add examples and README
* Update changelog and docs

.gitignore

@@ -159,3 +159,5 @@ com_crashlytics_export_strings.xml
 crashlytics.properties
 crashlytics-build.properties
 fabric.properties
+
+\.pytest_cache/

.idea/drf-yasg.iml

@@ -8,6 +8,7 @@
         <option name="manageScript" value="manage.py" />
         <option name="environment" value="&lt;map/&gt;" />
         <option name="doNotUseTestRunner" value="false" />
+        <option name="trackFilePattern" value="migrations" />
       </configuration>
     </facet>
   </component>
@@ -15,6 +16,7 @@
     <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$/docs/_build" />
       <excludeFolder url="file://$MODULE_DIR$/venv" />
     </content>
     <orderEntry type="jdk" jdkName="Python 3.6 (drf-yasg)" jdkType="Python SDK" />

.idea/inspectionProfiles/Project_Default.xml

@@ -10,11 +10,12 @@
     <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
       <option name="ourVersions">
         <value>
-          <list size="4">
+          <list size="5">
             <item index="0" class="java.lang.String" itemvalue="2.7" />
             <item index="1" class="java.lang.String" itemvalue="3.4" />
             <item index="2" class="java.lang.String" itemvalue="3.5" />
             <item index="3" class="java.lang.String" itemvalue="3.6" />
+            <item index="4" class="java.lang.String" itemvalue="3.7" />
           </list>
         </value>
       </option>

.idea/misc.xml

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

.travis.yml

@@ -9,6 +9,7 @@ python:
 
 env:
  - DRF=3.7
+ - DRF=3.8
 
 jobs:
   include:

README.rst

@@ -11,7 +11,7 @@ Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framewor
 
 Compatible with
 
-- **Django Rest Framework**: 3.7.7
+- **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
 
@@ -134,7 +134,7 @@ In ``urls.py``:
    )
 
    urlpatterns = [
-      url(r'^swagger(?P<format>.json|.yaml)$', schema_view.without_ui(cache_timeout=None), name='schema-json'),
+      url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=None), name='schema-json'),
       url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=None), name='schema-swagger-ui'),
       url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=None), name='schema-redoc'),
       ...
@@ -353,6 +353,12 @@ Integration with `djangorestframework-camel-case <https://github.com/vbabiy/djan
 provided out of the box - if you have ``djangorestframework-camel-case`` installed and your ``APIView`` uses
 ``CamelCaseJSONParser`` or ``CamelCaseJSONRenderer``, all property names will be converted to *camelCase* by default.
 
+djangorestframework-recursive
+===============================
+
+Integration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_ is
+provided out of the box - if you have ``djangorestframework-recursive`` installed.
+
 .. |travis| image:: https://img.shields.io/travis/axnsan12/drf-yasg/master.svg
    :target: https://travis-ci.org/axnsan12/drf-yasg
    :alt: Travis CI

docs/changelog.rst

@@ -3,6 +3,97 @@ Changelog
 #########
 
 
+*********
+**1.7.0**
+*********
+
+*Release date: Apr 27, 2018*
+
+- **ADDED:** added integration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_
+  (:issue:`109`, :pr:`110`, thanks to :ghuser:`rsichny`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.RecursiveFieldInspector`` to
+  your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **FIXED:** ``SchemaRef`` now supports cyclical references via the ``ignore_unresolved`` argument
+
+*********
+**1.6.2**
+*********
+
+*Release date: Apr 25, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.13.6
+- **IMPROVED:** switched ``ReDoc`` to version 2.0.0-alpha.17 (was 1.21.2); fixes :issue:`107`
+- **FIXED:** made documentation ordering of parameters stable for urls with multiple parameters (:issue:`105`, :pr:`106`)
+- **FIXED:** fixed crash when using a model ``ChoiceField`` of unknown child type
+
+*********
+**1.6.1**
+*********
+
+*Release date: Apr 01, 2018*
+
+- **ADDED:** added ``SUPPORTED_SUBMIT_METHODS`` ``swagger-ui`` setting
+
+*********
+**1.6.0**
+*********
+
+*Release date: Mar 24, 2018*
+
+- **IMPROVED:** ``OAUTH2_REDIRECT_URL`` will now default to the built in ``oauth2-redirect.html`` file
+
+*********
+**1.5.1**
+*********
+
+*Release date: Mar 18, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.13.0
+- **FIXED:** fixed a crash caused by ``serializers.OneToOneRel`` (:pr:`81`, thanks to :ghuser:`ko-pp`)
+
+*********
+**1.5.0**
+*********
+
+*Release date: Mar 12, 2018*
+
+- **IMPROVED:** ``serializers.HiddenField`` are now hidden (:issue:`78`, :pr:`79`, thanks to :ghuser:`therefromhere`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.HiddenFieldInspector`` to your
+  ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **IMPROVED:** type of model field is now detected for ``serializers.SlugRelatedField`` with ``read_only=True``
+  (:issue:`82`, :pr:`83`, thanks to :ghuser:`therefromhere`)
+
+*********
+**1.4.7**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **FIXED:** prevent crashes caused by attempting to delete object attributes which do not exist in the first place
+  (:issue:`76`)
+
+*********
+**1.4.6**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.12.0
+- **IMPROVED:** updated ``ReDoc`` to version 1.21.2
+
+*********
+**1.4.5**
+*********
+
+*Release date: Mar 05, 2018*
+
+- **FIXED:** fixed an issue with modification of ``swagger_auto_schema`` arguments in-place during introspection, which
+  would sometimes cause an incomplete Swagger document to be generated after the first pass (:issue:`74`, :pr:`75`)
+
 *********
 **1.4.4**
 *********

docs/conf.py

@@ -273,7 +273,7 @@ def role_github_user(name, rawtext, text, lineno, inliner, options=None, content
     options = options or {}
     content = content or []
 
-    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text):
+    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text, re.IGNORECASE):
         return sphinx_err(inliner, lineno, rawtext, '"%s" is not a valid GitHub username.' % text)
 
     ref = gh_user_uri.format(text)

docs/custom_spec.rst

@@ -87,8 +87,8 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
 
 * for ``ViewSet``, ``GenericViewSet``, ``ModelViewSet``, because each viewset corresponds to multiple **paths**, you have
   to decorate the *action methods*, i.e. ``list``, ``create``, ``retrieve``, etc. |br|
-  Additionally, ``@list_route``\ s or ``@detail_route``\ s defined on the viewset, like function based api views, can
-  respond to multiple HTTP methods and thus have multiple operations that must be decorated separately:
+  Additionally, ``@action``\ s, `@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:
 
 
    .. code-block:: python
@@ -96,13 +96,13 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
       class ArticleViewSet(viewsets.ModelViewSet):
          # method or 'methods' can be skipped because the list_route only handles a single method (GET)
          @swagger_auto_schema(operation_description='GET /articles/today/')
-         @list_route(methods=['get'])
+         @action(detail=False, methods=['get'])
          def today(self, request):
             ...
 
          @swagger_auto_schema(method='get', operation_description="GET /articles/{id}/image/")
          @swagger_auto_schema(method='post', operation_description="POST /articles/{id}/image/")
-         @detail_route(methods=['get', 'post'], parser_classes=(MultiPartParser,))
+         @action(detail=True, methods=['get', 'post'], parser_classes=(MultiPartParser,))
          def image(self, request, id=None):
             ...
 

docs/security.rst

@@ -63,3 +63,37 @@ settings described below were added as a result of discussion in issue :issue:`5
 The settings of interest can be found on the :ref:`settings page <oauth2-settings>`. Configuration options are similar
 to most OAuth client setups like web or mobile applications. Reading the relevant ``swagger-ui`` docmentation linked
 will also probably help.
+
+
+Example
+^^^^^^^
+
+A very simple working configuration was provided by :ghuser:`Vigrond`, originally at
+`https://github.com/Vigrond/django_oauth2_example <https://github.com/Vigrond/django_oauth2_example>`_.
+
+
+.. code-block:: python
+
+   SWAGGER_SETTINGS = {
+      'USE_SESSION_AUTH': False,
+      'SECURITY_DEFINITIONS': {
+         'Your App API - Swagger': {
+            'type': 'oauth2',
+            'authorizationUrl': '/yourapp/o/authorize',
+            'tokenUrl': '/yourapp/o/token/',
+            'flow": "accessCode',
+            'scopes': {
+             'read:groups': 'read groups',
+            }
+         }
+      },
+      'OAUTH2_CONFIG': {
+         'clientId': 'yourAppClientId',
+         'clientSecret': 'yourAppClientSecret',
+         'appName': 'your application name'
+      },
+   }
+
+If the OAuth2 provider requires you to provide the full absolute redirect URL, the default value for most
+``staticfiles`` configurations will be ``<origin>/static/drf-yasg/swagger-ui-dist/oauth2-redirect.html``. If this is
+not suitable for some reason, you can override the ``OAUTH2_REDIRECT_URL`` setting as appropriate.

docs/settings.rst

@@ -66,6 +66,8 @@ 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.HiddenFieldInspector' <.inspectors.HiddenFieldInspector>`, |br| \
+:class:`'drf_yasg.inspectors.RecursiveFieldInspector' <.inspectors.RecursiveFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.SimpleFieldInspector' <.inspectors.SimpleFieldInspector>`, |br| \
 :class:`'drf_yasg.inspectors.StringDefaultFieldInspector' <.inspectors.StringDefaultFieldInspector>`, |br| \
 ``]``
@@ -189,8 +191,8 @@ OPERATIONS_SORTER
 Sorting order for the operation list of each tag.
 
 * :python:`None`: show in the order returned by the server
-* :python:`alpha`: sort alphabetically by path
-* :python:`method`: sort by HTTP method
+* :python:`'alpha'`: sort alphabetically by path
+* :python:`'method'`: sort by HTTP method
 
 **Default**: :python:`None` |br|
 *Maps to parameter*: ``operationsSorter``
@@ -201,7 +203,7 @@ TAGS_SORTER
 Sorting order for tagged operation groups.
 
 * :python:`None`: Swagger UI default ordering
-* :python:`alpha`: sort alphabetically
+* :python:`'alpha'`: sort alphabetically
 
 **Default**: :python:`None` |br|
 *Maps to parameter*: ``tagsSorter``
@@ -211,9 +213,9 @@ DOC_EXPANSION
 
 Controls the default expansion setting for the operations and tags.
 
-* :python:`None`: everything is collapsed
-* :python:`list`: only tags are expanded
-* :python:`full`: all operations are expanded
+* :python:`'none'`: everything is collapsed
+* :python:`'list'`: only tags are expanded
+* :python:`'full'`: all operations are expanded
 
 **Default**: :python:`'list'` |br|
 *Maps to parameter*: ``docExpansion``
@@ -239,8 +241,8 @@ DEFAULT_MODEL_RENDERING
 
 Controls whether operations show the model structure or the example value by default.
 
-* :python:`model`: show the model fields by default
-* :python:`example`: show the example value by default
+* :python:`'model'`: show the model fields by default
+* :python:`'example'`: show the example value by default
 
 **Default**: :python:`'model'` |br|
 *Maps to parameter*: ``defaultModelRendering``
@@ -258,7 +260,10 @@ Controls how many levels are expaned by default when showing nested models.
 OAUTH2_REDIRECT_URL
 -------------------
 
-Used when OAuth2 authenitcation of API requests via swagger-ui is desired.
+Used when OAuth2 authenitcation of API requests via swagger-ui is desired. If ``None`` is passed, the
+``oauth2RedirectUrl`` parameter will be set to ``{% static 'drf-yasg/swagger-ui-dist/oauth2-redirect.html' %}``. This
+is the default `https://github.com/swagger-api/swagger-ui/blob/master/dist/oauth2-redirect.html <oauth2-redirect>`_
+file provided by ``swagger-ui``.
 
 **Default**: :python:`None` |br|
 *Maps to parameter*: ``oauth2RedirectUrl``
@@ -272,6 +277,15 @@ to the ``SwaggerUIBundle#initOAuth`` method, and must be a dictionary. See
 
 **Default**: :python:`{}`
 
+SUPPORTED_SUBMIT_METHODS
+------------------------
+
+List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations.
+This does not filter the operations from the display.
+
+**Default**: :python:`['get','put','post','delete','options','head','patch','trace']` |br|
+*Maps to parameter*: ``supportedSubmitMethods``
+
 ******************
 ``REDOC_SETTINGS``
 ******************

package.json

@@ -1,8 +1,8 @@
 {
   "name": "drf-yasg",
   "dependencies": {
-    "redoc": "^1.21.0",
-    "swagger-ui-dist": "^3.10.0"
+    "redoc": "^2.0.0-alpha.17",
+    "swagger-ui-dist": "^3.13.6"
   },
   "repository": {
     "type": "git",

requirements/testproj.txt

@@ -5,5 +5,6 @@ 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
+djangorestframework-recursive>=0.1.2
 dj-database-url>=0.4.2
 user_agents>=1.1.0

requirements/tox.txt

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

src/drf_yasg/app_settings.py

@@ -6,11 +6,13 @@ SWAGGER_DEFAULTS = {
 
     'DEFAULT_FIELD_INSPECTORS': [
         'drf_yasg.inspectors.CamelCaseJSONFilter',
+        'drf_yasg.inspectors.RecursiveFieldInspector',
         'drf_yasg.inspectors.ReferencingSerializerInspector',
-        'drf_yasg.inspectors.RelatedFieldInspector',
         'drf_yasg.inspectors.ChoiceFieldInspector',
         'drf_yasg.inspectors.FileFieldInspector',
         'drf_yasg.inspectors.DictFieldInspector',
+        'drf_yasg.inspectors.HiddenFieldInspector',
+        'drf_yasg.inspectors.RelatedFieldInspector',
         'drf_yasg.inspectors.SimpleFieldInspector',
         'drf_yasg.inspectors.StringDefaultFieldInspector',
     ],
@@ -45,6 +47,16 @@ SWAGGER_DEFAULTS = {
     'DEFAULT_MODEL_DEPTH': 3,
     'OAUTH2_REDIRECT_URL': None,
     'OAUTH2_CONFIG': {},
+    'SUPPORTED_SUBMIT_METHODS': [
+        'get',
+        'put',
+        'post',
+        'delete',
+        'options',
+        'head',
+        'patch',
+        'trace'
+    ],
 }
 
 REDOC_DEFAULTS = {

src/drf_yasg/generators.py

@@ -1,3 +1,4 @@
+import copy
 import logging
 import re
 from collections import OrderedDict, defaultdict
@@ -355,9 +356,9 @@ class OpenAPISchemaGenerator(object):
 
         view_inspector = view_inspector_cls(view, path, method, components, request, overrides)
         operation = view_inspector.get_operation(operation_keys)
-        if set(operation.consumes) == set(self.consumes):
+        if 'consumes' in operation and set(operation.consumes) == set(self.consumes):
             del operation.consumes
-        if set(operation.produces) == set(self.produces):
+        if 'produces' in operation and set(operation.produces) == set(self.produces):
             del operation.produces
         return operation
 
@@ -388,7 +389,7 @@ class OpenAPISchemaGenerator(object):
         if method in overrides:
             overrides = overrides[method]
 
-        return overrides
+        return copy.deepcopy(overrides)
 
     def get_path_parameters(self, path, view_cls):
         """Return a list of Parameter instances corresponding to any templated path variables.
@@ -402,15 +403,15 @@ class OpenAPISchemaGenerator(object):
         queryset = getattr(view_cls, 'queryset', None)
         model = getattr(getattr(view_cls, 'queryset', None), 'model', None)
 
-        for variable in uritemplate.variables(path):
+        for variable in sorted(uritemplate.variables(path)):
             model, model_field = get_queryset_field(queryset, variable)
             attrs = get_basic_type_info(model_field) or {'type': openapi.TYPE_STRING}
             if getattr(view_cls, 'lookup_field', None) == variable and attrs['type'] == openapi.TYPE_STRING:
                 attrs['pattern'] = getattr(view_cls, 'lookup_value_regex', attrs.get('pattern', None))
 
-            if model_field and model_field.help_text:
+            if model_field and getattr(model_field, 'help_text', False):
                 description = force_text(model_field.help_text)
-            elif model_field and model_field.primary_key:
+            elif model_field and getattr(model_field, 'primary_key', False):
                 description = get_pk_description(model, model_field)
             else:
                 description = None

src/drf_yasg/inspectors/__init__.py

@@ -3,8 +3,9 @@ from .base import (
     BaseInspector, FieldInspector, FilterInspector, NotHandled, PaginatorInspector, SerializerInspector, ViewInspector
 )
 from .field import (
-    CamelCaseJSONFilter, ChoiceFieldInspector, DictFieldInspector, FileFieldInspector, InlineSerializerInspector,
-    ReferencingSerializerInspector, RelatedFieldInspector, SimpleFieldInspector, StringDefaultFieldInspector
+    CamelCaseJSONFilter, ChoiceFieldInspector, DictFieldInspector, FileFieldInspector, HiddenFieldInspector,
+    InlineSerializerInspector, RecursiveFieldInspector, ReferencingSerializerInspector, RelatedFieldInspector,
+    SimpleFieldInspector, StringDefaultFieldInspector
 )
 from .query import CoreAPICompatInspector, DjangoRestResponsePagination
 from .view import SwaggerAutoSchema
@@ -22,9 +23,9 @@ __all__ = [
     'CoreAPICompatInspector', 'DjangoRestResponsePagination',
 
     # field inspectors
-    'InlineSerializerInspector', 'ReferencingSerializerInspector', 'RelatedFieldInspector', 'SimpleFieldInspector',
-    'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector', 'StringDefaultFieldInspector',
-    'CamelCaseJSONFilter',
+    'InlineSerializerInspector', 'RecursiveFieldInspector', 'ReferencingSerializerInspector', 'RelatedFieldInspector',
+    'SimpleFieldInspector', 'FileFieldInspector', 'ChoiceFieldInspector', 'DictFieldInspector',
+    'StringDefaultFieldInspector', 'CamelCaseJSONFilter', 'HiddenFieldInspector',
 
     # view inspectors
     'SwaggerAutoSchema',

src/drf_yasg/inspectors/field.py

@@ -10,7 +10,7 @@ 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
+from ..utils import decimal_as_float, filter_none, get_serializer_ref_name
 from .base import FieldInspector, NotHandled, SerializerInspector
 
 logger = logging.getLogger(__name__)
@@ -55,23 +55,12 @@ class InlineSerializerInspector(SerializerInspector):
             if swagger_object_type != openapi.Schema:
                 raise SwaggerGenerationError("cannot instantiate nested serializer as " + swagger_object_type.__name__)
 
-            serializer = field
-            serializer_meta = getattr(serializer, 'Meta', None)
-            serializer_name = type(serializer).__name__
-            if hasattr(serializer_meta, 'ref_name'):
-                ref_name = serializer_meta.ref_name
-            elif serializer_name == 'NestedSerializer' and isinstance(serializer, serializers.ModelSerializer):
-                logger.debug("Forcing inline output for ModelSerializer named 'NestedSerializer': " + str(serializer))
-                ref_name = None
-            else:
-                ref_name = serializer_name
-                if ref_name.endswith('Serializer'):
-                    ref_name = ref_name[:-len('Serializer')]
+            ref_name = get_serializer_ref_name(field)
 
             def make_schema_definition():
                 properties = OrderedDict()
                 required = []
-                for property_name, child in serializer.fields.items():
+                for property_name, child in field.fields.items():
                     property_name = self.get_property_name(property_name)
                     prop_kwargs = {
                         'read_only': child.read_only or None
@@ -89,9 +78,9 @@ class InlineSerializerInspector(SerializerInspector):
                     properties=properties,
                     required=required or None,
                 )
-                if not ref_name:
+                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 named, which is confusing
+                    # but is visually displayed like the model name, which is confusing
                     # it is better to just remove title from inline models
                     del result.title
                 return result
@@ -161,7 +150,11 @@ def get_related_model(model, source):
     :return: related model or ``None``
     """
     try:
-        return getattr(model, source).rel.related_model
+        descriptor = getattr(model, source)
+        try:
+            return descriptor.rel.related_model
+        except Exception:
+            return descriptor.field.remote_field.model
     except Exception:  # pragma: no cover
         return None
 
@@ -406,7 +399,9 @@ class ChoiceFieldInspector(FieldInspector):
                 model = getattr(getattr(serializer, 'Meta'), 'model')
                 model_field = get_model_field(model, field.source)
                 if model_field:
-                    enum_type = get_basic_type_info(model_field).get('type', enum_type)
+                    model_type = get_basic_type_info(model_field)
+                    if model_type:
+                        enum_type = model_type.get('type', enum_type)
 
             if isinstance(field, serializers.MultipleChoiceField):
                 return SwaggerType(
@@ -465,11 +460,21 @@ class DictFieldInspector(FieldInspector):
         return NotHandled
 
 
+class HiddenFieldInspector(FieldInspector):
+    """Hide ``HiddenField``."""
+
+    def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+        if isinstance(field, serializers.HiddenField):
+            return None
+
+        return NotHandled
+
+
 class 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 HiddenField JSONField
+        # TODO unhandled fields: TimeField JSONField
         SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
         return SwaggerType(type=openapi.TYPE_STRING)
 
@@ -515,3 +520,24 @@ else:
                 return camelize_schema(result, self.components)
 
             return result
+
+try:
+    from rest_framework_recursive.fields import RecursiveField
+except ImportError:
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+        pass
+else:
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+        def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+            if isinstance(field, RecursiveField) and swagger_object_type == openapi.Schema:
+                assert use_references is True, "Can not create schema for RecursiveField when use_references is False"
+
+                ref_name = get_serializer_ref_name(field.proxied)
+                assert ref_name is not None, "Can not create RecursiveField schema for inline ModelSerializer"
+
+                return openapi.SchemaRef(self.components.with_scope(openapi.SCHEMA_DEFINITIONS), ref_name,
+                                         ignore_unresolved=True)
+
+            return NotHandled

src/drf_yasg/openapi.py

@@ -425,7 +425,7 @@ 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 list[.Schema,.SchemaRef] properties: object properties; required if `type` is ``object``
+        :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``
@@ -437,7 +437,7 @@ class Schema(SwaggerDict):
         super(Schema, self).__init__(**extra)
         if required is True or required is False:
             # common error
-            raise AssertionError("the `requires` attribute of schema must be an "
+            raise AssertionError("the `required` attribute of schema must be an "
                                  "array of required property names, not a boolean!")
         assert type, "type is required!"
         self.title = title
@@ -466,7 +466,7 @@ class Schema(SwaggerDict):
 class _Ref(SwaggerDict):
     ref_name_re = re.compile(r"#/(?P<scope>.+)/(?P<name>[^/]+)$")
 
-    def __init__(self, resolver, name, scope, expected_type):
+    def __init__(self, resolver, name, scope, expected_type, ignore_unresolved=False):
         """Base class for all reference types. A reference object has only one property, ``$ref``, which must be a JSON
         reference to a valid object in the specification, e.g. ``#/definitions/Article`` to refer to an article model.
 
@@ -474,13 +474,15 @@ 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
         """
         super(_Ref, self).__init__()
         assert not type(self) == _Ref, "do not instantiate _Ref directly"
         ref_name = "#/{scope}/{name}".format(scope=scope, name=name)
-        obj = resolver.get(name, scope)
-        assert isinstance(obj, expected_type), ref_name + " is a {actual}, not a {expected}" \
-            .format(actual=type(obj).__name__, expected=expected_type.__name__)
+        if not ignore_unresolved:
+            obj = resolver.get(name, scope)
+            assert isinstance(obj, expected_type), ref_name + " is a {actual}, not a {expected}" \
+                .format(actual=type(obj).__name__, expected=expected_type.__name__)
         self.ref = ref_name
 
     def resolve(self, resolver):
@@ -502,14 +504,15 @@ class _Ref(SwaggerDict):
 
 
 class SchemaRef(_Ref):
-    def __init__(self, resolver, schema_name):
+    def __init__(self, resolver, schema_name, ignore_unresolved=False):
         """Adds a reference to a named Schema defined in the ``#/definitions/`` object.
 
         :param .ReferenceResolver resolver: component resolver which must contain the definition
         :param str schema_name: schema name
+        :param bool ignore_unresolved: allow the reference to be not defined in resolver
         """
         assert SCHEMA_DEFINITIONS in resolver.scopes
-        super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema)
+        super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema, ignore_unresolved)
 
 
 Schema.OR_REF = (Schema, SchemaRef)

src/drf_yasg/renderers.py

@@ -94,6 +94,7 @@ class _UIRenderer(BaseRenderer):
             'defaultModelExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
             'defaultModelsExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
             'oauth2RedirectUrl': swagger_settings.OAUTH2_REDIRECT_URL,
+            'supportedSubmitMethods': swagger_settings.SUPPORTED_SUBMIT_METHODS,
         }
         data = {k: v for k, v in data.items() if v is not None}
         if swagger_settings.VALIDATOR_URL != '':
@@ -131,11 +132,3 @@ class ReDocRenderer(_UIRenderer):
     """
     template = 'drf-yasg/redoc.html'
     format = 'redoc'
-
-
-class ReDocAlphaRenderer(_UIRenderer):
-    """Renders a ReDoc web interface for schema browisng.
-    Also requires :class:`.OpenAPIRenderer` as an available renderer on the same view.
-    """
-    template = 'drf-yasg/redoc-alpha.html'
-    format = 'redoc'

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

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

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

@@ -38,7 +38,7 @@ function initSwaggerUi() {
         ],
         layout: "StandaloneLayout",
         filter: true,
-        requestInterceptor: function(request) {
+        requestInterceptor: function (request) {
             var headers = request.headers || {};
             var csrftoken = document.querySelector("[name=csrfmiddlewaretoken]");
             if (csrftoken) {
@@ -49,8 +49,15 @@ function initSwaggerUi() {
     };
 
     var swaggerSettings = JSON.parse(document.getElementById('swagger-settings').innerHTML);
-    console.log(swaggerSettings);
+    if (!('oauth2RedirectUrl' in swaggerSettings)) {
+        var oauth2RedirectUrl = document.getElementById('oauth2-redirect-url');
+        if (oauth2RedirectUrl) {
+            swaggerSettings['oauth2RedirectUrl'] = oauth2RedirectUrl.href;
+            oauth2RedirectUrl.parentNode.removeChild(oauth2RedirectUrl);
+        }
+    }
 
+    console.log(swaggerSettings);
     for (var p in swaggerSettings) {
         if (swaggerSettings.hasOwnProperty(p)) {
             swaggerConfig[p] = swaggerSettings[p];

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

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

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

@@ -67,6 +67,8 @@
 <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
 <script src="{% static 'drf-yasg/swagger-ui-init.js' %}"></script>
 
+<a id="oauth2-redirect-url" href="{% static 'drf-yasg/swagger-ui-dist/oauth2-redirect.html' %}" class="hidden"></a>
+
 <div id="django-session-auth" class="hidden">
     {% if USE_SESSION_AUTH %}
         {% csrf_token %}

src/drf_yasg/utils.py

@@ -11,10 +11,15 @@ from rest_framework.views import APIView
 
 logger = logging.getLogger(__name__)
 
-#: used to forcibly remove the body of a request via :func:`.swagger_auto_schema`
-no_body = object()
 
-unset = object()
+class no_body(object):
+    """Used as a sentinel value to forcibly remove the body of a request via :func:`.swagger_auto_schema`."""
+    pass
+
+
+class unset(object):
+    """Used as a sentinel value for function parameters not set by the caller where ``None`` would be a valid value."""
+    pass
 
 
 def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_body=None, query_serializer=None,
@@ -33,7 +38,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
     :param .inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object;
         this overrides both the class-level ``swagger_schema`` attribute and the ``DEFAULT_AUTO_SCHEMA_CLASS``
         setting, and can be set to ``None`` to prevent this operation from being generated
-    :param .Schema,.SchemaRef,.Serializer request_body: custom request body, or :data:`.no_body`. The value given here
+    :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'``.
 
         A Schema or SchemaRef is not valid if this request consumes form-data, because ``form`` and ``body`` parameters
@@ -109,7 +114,7 @@ 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 a detail_route or list_route, it will have a bind_to_methods attribute
+        # if the method is an @action, it will have a bind_to_methods attribute
         bind_to_methods = getattr(view_method, 'bind_to_methods', [])
         # if the method is actually a function based view (@api_view), it will have a 'cls' attribute
         view_cls = getattr(view_method, 'cls', None)
@@ -121,7 +126,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
         _methods = methods
         if methods or method:
             assert available_methods or http_method_names, "`method` or `methods` can only be specified " \
-                                                           "on @detail_route or @api_view views"
+                                                           "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"
@@ -133,13 +138,13 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
             assert not any(mth in existing_data for mth in _methods), "http method defined multiple times"
 
         if available_methods:
-            # detail_route, list_route or api_view
+            # action or api_view
             assert bool(http_method_names) != bool(bind_to_methods), "this should never happen"
 
             if len(available_methods) > 1:
                 assert _methods, \
-                    "on multi-method api_view, detail_route or list_route, you must specify swagger_auto_schema on " \
-                    "a per-method basis using one of the `method` or `methods` arguments"
+                    "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
@@ -151,8 +156,9 @@ 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 a detail_route or list_route; you " \
-                "should also ensure that you put the swagger_auto_schema decorator AFTER (above) the _route decorator"
+                "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 " \
+                "AFTER (above) the _route decorator"
             assert not existing_data, "swagger_auto_schema applied twice to method"
             view_method._swagger_auto_schema = data
 
@@ -178,7 +184,7 @@ def is_list_view(path, method, view):
         return True
 
     if action in ('retrieve', 'update', 'partial_update', 'destroy') or detail is True or suffix == 'Instance':
-        # a detail_route is surely not a list route
+        # a detail action is surely not a list route
         return False
 
     # for GenericAPIView, if it's a detail view it can't also be a list view
@@ -289,3 +295,25 @@ def decimal_as_float(field):
     if isinstance(field, serializers.DecimalField) or isinstance(field, models.DecimalField):
         return not getattr(field, 'coerce_to_string', rest_framework_settings.COERCE_DECIMAL_TO_STRING)
     return False
+
+
+def get_serializer_ref_name(serializer):
+    """
+    Get serializer's ref_name (or None for ModelSerializer if it is named 'NestedSerializer')
+
+    :param serializer: Serializer instance
+    :return: Serializer's ref_name or None for inline serializer
+    :rtype: str or None
+    """
+    serializer_meta = getattr(serializer, 'Meta', None)
+    serializer_name = type(serializer).__name__
+    if hasattr(serializer_meta, 'ref_name'):
+        ref_name = serializer_meta.ref_name
+    elif serializer_name == 'NestedSerializer' and isinstance(serializer, serializers.ModelSerializer):
+        logger.debug("Forcing inline output for ModelSerializer named 'NestedSerializer': " + str(serializer))
+        ref_name = None
+    else:
+        ref_name = serializer_name
+        if ref_name.endswith('Serializer'):
+            ref_name = ref_name[:-len('Serializer')]
+    return ref_name

src/drf_yasg/views.py

@@ -12,15 +12,12 @@ from rest_framework.views import APIView
 
 from .app_settings import swagger_settings
 from .generators import OpenAPISchemaGenerator
-from .renderers import (
-    OpenAPIRenderer, ReDocAlphaRenderer, ReDocRenderer, SwaggerJSONRenderer, SwaggerUIRenderer, SwaggerYAMLRenderer
-)
+from .renderers import OpenAPIRenderer, ReDocRenderer, SwaggerJSONRenderer, SwaggerUIRenderer, SwaggerYAMLRenderer
 
 SPEC_RENDERERS = (SwaggerYAMLRenderer, SwaggerJSONRenderer, OpenAPIRenderer)
 UI_RENDERERS = {
     'swagger': (SwaggerUIRenderer, ReDocRenderer),
     'redoc': (ReDocRenderer, SwaggerUIRenderer),
-    'redoc-alpha': (ReDocAlphaRenderer, ReDocRenderer, SwaggerUIRenderer)
 }
 
 

testproj/articles/migrations/0001_initial.py

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

testproj/articles/migrations/0002_article_article_type.py

@@ -1,18 +0,0 @@
-# Generated by Django 2.0.1 on 2018-02-26 18:32
-
-from django.db import migrations, models
-
-
-class Migration(migrations.Migration):
-
-    dependencies = [
-        ('articles', '0001_initial'),
-    ]
-
-    operations = [
-        migrations.AddField(
-            model_name='article',
-            name='article_type',
-            field=models.PositiveSmallIntegerField(choices=[(1, 'first'), (2, 'second'), (3, 'third'), (7, 'seven'), (8, 'eight')], help_text='IntegerField declared on model with choices=(...) and exposed via ModelSerializer', null=True),
-        ),
-    ]

testproj/articles/models.py

@@ -1,3 +1,5 @@
+import uuid
+
 from django.db import models
 
 
@@ -14,3 +16,14 @@ class Article(models.Model):
     )
 
     cover = models.ImageField(upload_to='article/original/', blank=True)
+    group = models.ForeignKey('ArticleGroup', related_name='articles_as_main', blank=True, default=None,
+                              on_delete=models.PROTECT)
+    original_group = models.ForeignKey('ArticleGroup', related_name='articles_as_original', blank=True, default=None,
+                                       on_delete=models.PROTECT)
+
+
+class ArticleGroup(models.Model):
+    uuid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+
+    title = models.CharField(help_text="title model help_text", max_length=255, blank=False, unique=True)
+    slug = models.SlugField(help_text="slug model help_text", unique=True, blank=True)

testproj/articles/serializers.py

@@ -1,7 +1,7 @@
 from django.utils.translation import ugettext_lazy as _
 from rest_framework import serializers
 
-from articles.models import Article
+from articles.models import Article, ArticleGroup
 
 
 class ArticleSerializer(serializers.ModelSerializer):
@@ -12,11 +12,13 @@ class ArticleSerializer(serializers.ModelSerializer):
     )
     uuid = serializers.UUIDField(help_text="should articles have UUIDs?", read_only=True)
     cover_name = serializers.FileField(use_url=False, source='cover', read_only=True)
+    group = serializers.SlugRelatedField(slug_field='uuid', queryset=ArticleGroup.objects.all())
+    original_group = serializers.SlugRelatedField(slug_field='uuid', read_only=True)
 
     class Meta:
         model = Article
         fields = ('title', 'author', 'body', 'slug', 'date_created', 'date_modified',
-                  'references', 'uuid', 'cover', 'cover_name', 'article_type')
+                  'references', 'uuid', 'cover', 'cover_name', 'article_type', 'group', 'original_group', )
         read_only_fields = ('date_created', 'date_modified',
                             'references', 'uuid', 'cover_name')
         lookup_field = 'slug'

testproj/articles/views.py

@@ -3,6 +3,7 @@ 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
@@ -89,23 +90,48 @@ class ArticleViewSet(viewsets.ModelViewSet):
 
     swagger_schema = NoTitleAutoSchema
 
-    @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)
+    try:
+        from rest_framework.decorators import action
 
-    @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,))
-    def image(self, request, slug=None):
-        """
-        image method docstring
-        """
-        pass
+        @swagger_auto_schema(auto_schema=NoPagingAutoSchema, filter_inspectors=[DjangoFilterDescriptionInspector])
+        @action(detail=False, methods=['get'])
+        def today(self, request):
+            today_min = datetime.datetime.combine(datetime.date.today(), datetime.time.min)
+            today_max = datetime.datetime.combine(datetime.date.today(), datetime.time.max)
+            articles = self.get_queryset().filter(date_created__range=(today_min, today_max)).all()
+            serializer = self.serializer_class(articles, many=True)
+            return Response(serializer.data)
+
+        @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,))
+        def image(self, request, slug=None):
+            """
+            image method docstring
+            """
+            pass
 
     def update(self, request, *args, **kwargs):
         """update method docstring"""

testproj/people/apps.py

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

testproj/people/migrations/0001_initial.py

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

testproj/people/models.py

@@ -0,0 +1,10 @@
+from django.db import models
+
+
+class Identity(models.Model):
+    firstName = models.CharField(max_length=30, null=True)
+    lastName = models.CharField(max_length=30, null=True)
+
+
+class Person(models.Model):
+    identity = models.OneToOneField(Identity, related_name='person', on_delete=models.PROTECT)

testproj/people/serializers.py

@@ -0,0 +1,23 @@
+from rest_framework import serializers
+
+from .models import Identity, Person
+
+
+class IdentitySerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Identity
+        fields = '__all__'
+
+
+class PersonSerializer(serializers.ModelSerializer):
+    identity = IdentitySerializer()
+
+    class Meta:
+        model = Person
+        fields = '__all__'
+
+    def create(self, validated_data):
+        identity = Identity(**validated_data['identity'])
+        identity.save()
+        validated_data['identity'] = identity
+        return super().create(validated_data)

testproj/people/urls.py

@@ -0,0 +1,26 @@
+from django.conf.urls import url
+
+from .views import IdentityViewSet, PersonViewSet
+
+person_list = PersonViewSet.as_view({
+    'get': 'list',
+    'post': 'create'
+})
+person_detail = PersonViewSet.as_view({
+    'get': 'retrieve',
+    'patch': 'partial_update',
+    'delete': 'destroy'
+})
+
+identity_detail = IdentityViewSet.as_view({
+    'get': 'retrieve',
+    'patch': 'partial_update',
+})
+
+urlpatterns = (
+    url(r'^$', person_list, name='people-list'),
+    url(r'^(?P<pk>[0-9]+)$', person_detail, name='person-detail'),
+
+    url(r'^(?P<person>[0-9]+)/identity$', identity_detail,
+        name='person-identity'),
+)

testproj/people/views.py

@@ -0,0 +1,16 @@
+from rest_framework import viewsets
+
+from .models import Identity, Person
+from .serializers import IdentitySerializer, PersonSerializer
+
+
+class PersonViewSet(viewsets.ModelViewSet):
+    model = Person
+    queryset = Person.objects
+    serializer_class = PersonSerializer
+
+
+class IdentityViewSet(viewsets.ModelViewSet):
+    model = Identity
+    queryset = Identity.objects
+    serializer_class = IdentitySerializer

testproj/snippets/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 2.0 on 2017-12-23 09:07
+# Generated by Django 2.0.1 on 2018-03-18 18:32
 
 from django.conf import settings
 from django.db import migrations, models

testproj/testproj/settings/base.py

@@ -27,6 +27,7 @@ INSTALLED_APPS = [
     'users',
     'articles',
     'todo',
+    'people'
 ]
 
 MIDDLEWARE = [

testproj/testproj/urls.py

@@ -51,7 +51,7 @@ 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'),
     url(r'^redoc/$', SchemaView.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
-    url(r'^redoc-alpha/$', SchemaView.with_ui('redoc-alpha', cache_timeout=0), name='schema-redoc-alpha'),
+
     url(r'^cached/swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=None), name='cschema-json'),
     url(r'^cached/swagger/$', SchemaView.with_ui('swagger', cache_timeout=None), name='cschema-swagger-ui'),
     url(r'^cached/redoc/$', SchemaView.with_ui('redoc', cache_timeout=None), name='cschema-redoc'),
@@ -63,5 +63,6 @@ urlpatterns = [
     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),
 ]

testproj/todo/migrations/0001_initial.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-# Generated by Django 1.11 on 2018-02-21 23:26
-from __future__ import unicode_literals
+# Generated by Django 2.0.1 on 2018-03-18 18:32
 
 from django.db import migrations, models
 import django.db.models.deletion

testproj/todo/migrations/0002_todotree.py

@@ -0,0 +1,22 @@
+# Generated by Django 2.0.4 on 2018-04-26 13:06
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('todo', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='TodoTree',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=50)),
+                ('parent', models.ForeignKey(null=True, on_delete=django.db.models.deletion.CASCADE,
+                                             related_name='children', to='todo.TodoTree')),
+            ],
+        ),
+    ]

testproj/todo/models.py

@@ -13,3 +13,8 @@ class TodoAnother(models.Model):
 class TodoYetAnother(models.Model):
     todo = models.ForeignKey(TodoAnother, on_delete=models.CASCADE)
     title = models.CharField(max_length=50)
+
+
+class TodoTree(models.Model):
+    parent = models.ForeignKey('self', on_delete=models.CASCADE, related_name='children', null=True)
+    title = models.CharField(max_length=50)

testproj/todo/serializer.py

@@ -1,12 +1,16 @@
+from django.utils import timezone
 from rest_framework import serializers
+from rest_framework_recursive.fields import RecursiveField
 
-from .models import Todo, TodoAnother, TodoYetAnother
+from .models import Todo, TodoAnother, TodoTree, TodoYetAnother
 
 
 class TodoSerializer(serializers.ModelSerializer):
     class Meta:
         model = Todo
-        fields = ('title',)
+        fields = ('title', 'a_hidden_field',)
+
+    a_hidden_field = serializers.HiddenField(default=timezone.now)
 
 
 class TodoAnotherSerializer(serializers.ModelSerializer):
@@ -22,3 +26,22 @@ class TodoYetAnotherSerializer(serializers.ModelSerializer):
         model = TodoYetAnother
         fields = ('title', 'todo')
         depth = 2
+
+
+class TodoTreeSerializer(serializers.ModelSerializer):
+    children = serializers.ListField(child=RecursiveField(), source='children.all')
+
+    class Meta:
+        model = TodoTree
+        fields = ('id', 'title', 'children')
+
+
+class TodoRecursiveSerializer(serializers.ModelSerializer):
+    parent = RecursiveField(read_only=True)
+    parent_id = serializers.PrimaryKeyRelatedField(queryset=TodoTree.objects.all(), pk_field=serializers.IntegerField(),
+                                                   write_only=True, allow_null=True, required=False, default=None,
+                                                   source='parent')
+
+    class Meta:
+        model = TodoTree
+        fields = ('id', 'title', 'parent', 'parent_id')

testproj/todo/urls.py

@@ -1,3 +1,4 @@
+from django.conf.urls import url
 from rest_framework import routers
 
 from todo import views
@@ -6,5 +7,12 @@ router = routers.DefaultRouter()
 router.register(r'', views.TodoViewSet)
 router.register(r'another', views.TodoAnotherViewSet)
 router.register(r'yetanother', views.TodoYetAnotherViewSet)
+router.register(r'tree', views.TodoTreeView)
+router.register(r'recursive', views.TodoRecursiveView)
 
 urlpatterns = router.urls
+
+urlpatterns += [
+    url(r'^(?P<todo_id>\d+)/yetanother/(?P<yetanother_id>\d+)/$',
+        views.NestedTodoView.as_view(), ),
+]

testproj/todo/views.py

@@ -1,7 +1,10 @@
 from rest_framework import viewsets
+from rest_framework.generics import RetrieveAPIView
 
-from .models import Todo, TodoAnother, TodoYetAnother
-from .serializer import TodoAnotherSerializer, TodoSerializer, TodoYetAnotherSerializer
+from .models import Todo, TodoAnother, TodoTree, TodoYetAnother
+from .serializer import (
+    TodoAnotherSerializer, TodoRecursiveSerializer, TodoSerializer, TodoTreeSerializer, TodoYetAnotherSerializer
+)
 
 
 class TodoViewSet(viewsets.ReadOnlyModelViewSet):
@@ -20,3 +23,17 @@ class TodoAnotherViewSet(viewsets.ReadOnlyModelViewSet):
 class TodoYetAnotherViewSet(viewsets.ReadOnlyModelViewSet):
     queryset = TodoYetAnother.objects.all()
     serializer_class = TodoYetAnotherSerializer
+
+
+class NestedTodoView(RetrieveAPIView):
+    serializer_class = TodoYetAnotherSerializer
+
+
+class TodoTreeView(viewsets.ReadOnlyModelViewSet):
+    queryset = TodoTree.objects.all()
+    serializer_class = TodoTreeSerializer
+
+
+class TodoRecursiveView(viewsets.ModelViewSet):
+    queryset = TodoTree.objects.all()
+    serializer_class = TodoRecursiveSerializer

tests/reference.yaml

@@ -234,6 +234,113 @@ paths:
         type: string
         format: slug
         pattern: '[a-z0-9]+(?:-[a-z0-9]+)'
+  /people/:
+    get:
+      operationId: people_list
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Person'
+      tags:
+        - people
+    post:
+      operationId: people_create
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Person'
+      responses:
+        '201':
+          description: ''
+          schema:
+            $ref: '#/definitions/Person'
+      tags:
+        - people
+    parameters: []
+  /people/{id}:
+    get:
+      operationId: people_read
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Person'
+      tags:
+        - people
+    patch:
+      operationId: people_partial_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Person'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Person'
+      tags:
+        - people
+    delete:
+      operationId: people_delete
+      description: ''
+      parameters: []
+      responses:
+        '204':
+          description: ''
+      tags:
+        - people
+    parameters:
+      - name: id
+        in: path
+        description: A unique integer value identifying this person.
+        required: true
+        type: integer
+  /people/{person}/identity:
+    get:
+      operationId: people_identity_read
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Identity'
+      tags:
+        - people
+    patch:
+      operationId: people_identity_partial_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Identity'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/Identity'
+      tags:
+        - people
+    parameters:
+      - name: person
+        in: path
+        required: true
+        type: string
   /plain/:
     get:
       operationId: plain_list
@@ -388,6 +495,129 @@ paths:
         description: A unique integer value identifying this todo another.
         required: true
         type: integer
+  /todo/recursive/:
+    get:
+      operationId: todo_recursive_list
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/TodoRecursive'
+      tags:
+        - todo
+    post:
+      operationId: todo_recursive_create
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      responses:
+        '201':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      tags:
+        - todo
+    parameters: []
+  /todo/recursive/{id}/:
+    get:
+      operationId: todo_recursive_read
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      tags:
+        - todo
+    put:
+      operationId: todo_recursive_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      tags:
+        - todo
+    patch:
+      operationId: todo_recursive_partial_update
+      description: ''
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoRecursive'
+      tags:
+        - todo
+    delete:
+      operationId: todo_recursive_delete
+      description: ''
+      parameters: []
+      responses:
+        '204':
+          description: ''
+      tags:
+        - todo
+    parameters:
+      - name: id
+        in: path
+        description: A unique integer value identifying this todo tree.
+        required: true
+        type: integer
+  /todo/tree/:
+    get:
+      operationId: todo_tree_list
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/TodoTree'
+      tags:
+        - todo
+    parameters: []
+  /todo/tree/{id}/:
+    get:
+      operationId: todo_tree_read
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoTree'
+      tags:
+        - todo
+    parameters:
+      - name: id
+        in: path
+        description: A unique integer value identifying this todo tree.
+        required: true
+        type: integer
   /todo/yetanother/:
     get:
       operationId: todo_yetanother_list
@@ -439,6 +669,27 @@ paths:
         description: A unique integer value identifying this todo.
         required: true
         type: integer
+  /todo/{todo_id}/yetanother/{yetanother_id}/:
+    get:
+      operationId: todo_yetanother_read
+      description: ''
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          schema:
+            $ref: '#/definitions/TodoYetAnother'
+      tags:
+        - todo
+    parameters:
+      - name: todo_id
+        in: path
+        required: true
+        type: string
+      - name: yetanother_id
+        in: path
+        required: true
+        type: string
   /users/:
     get:
       operationId: users_list
@@ -542,6 +793,7 @@ definitions:
     required:
       - title
       - body
+      - group
     type: object
     properties:
       title:
@@ -601,6 +853,40 @@ definitions:
           - 3
           - 7
           - 8
+      group:
+        type: string
+        format: uuid
+      original_group:
+        type: string
+        format: uuid
+        readOnly: true
+  Identity:
+    title: Identity
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      firstName:
+        title: FirstName
+        type: string
+        maxLength: 30
+      lastName:
+        title: LastName
+        type: string
+        maxLength: 30
+  Person:
+    required:
+      - identity
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      identity:
+        $ref: '#/definitions/Identity'
   Project:
     required:
       - projectName
@@ -1174,6 +1460,42 @@ definitions:
         maxLength: 50
       todo:
         $ref: '#/definitions/Todo'
+  TodoRecursive:
+    required:
+      - title
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      title:
+        title: Title
+        type: string
+        maxLength: 50
+      parent:
+        $ref: '#/definitions/TodoRecursive'
+      parent_id:
+        type: integer
+        title: Parent id
+  TodoTree:
+    required:
+      - title
+      - children
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      title:
+        title: Title
+        type: string
+        maxLength: 50
+      children:
+        type: array
+        items:
+          $ref: '#/definitions/TodoTree'
   TodoYetAnother:
     required:
       - title

tests/test_schema_generator.py

@@ -2,11 +2,14 @@ import json
 from collections import OrderedDict
 
 import pytest
+from rest_framework import routers, serializers, viewsets
+from rest_framework.response import Response
 
 from drf_yasg import codecs, openapi
 from drf_yasg.codecs import yaml_sane_load
 from drf_yasg.errors import SwaggerGenerationError
 from drf_yasg.generators import OpenAPISchemaGenerator
+from drf_yasg.utils import swagger_auto_schema
 
 
 def test_schema_is_valid(swagger, codec_yaml):
@@ -79,3 +82,34 @@ def test_securiy_requirements(swagger_settings, mock_schema_request):
 
     swagger = generator.get_schema(mock_schema_request, public=True)
     assert swagger['security'] == []
+
+
+def test_replaced_serializer():
+    class DetailSerializer(serializers.Serializer):
+        detail = serializers.CharField()
+
+    class DetailViewSet(viewsets.ViewSet):
+        serializer_class = DetailSerializer
+
+        @swagger_auto_schema(responses={404: openapi.Response("Not found or Not accessible", DetailSerializer)})
+        def retrieve(self, request, pk=None):
+            serializer = DetailSerializer({'detail': None})
+            return Response(serializer.data)
+
+    router = routers.DefaultRouter()
+    router.register(r'details', DetailViewSet, base_name='details')
+
+    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)
+        assert 'Detail' in swagger['definitions']
+        assert 'detail' in swagger['definitions']['Detail']['properties']
+        responses = swagger['paths']['/details/{id}/']['get']['responses']
+        assert '404' in responses
+        assert responses['404']['schema']['$ref'] == "#/definitions/Detail"

tox.ini

@@ -1,13 +1,14 @@
 [tox]
 envlist =
     py27-django111-drf37,
-    py{34,35,36}-django{111,20}-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
 
 [testenv]
@@ -16,6 +17,7 @@ deps =
     django20: Django>=2.0,<2.1
 
     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
@@ -63,7 +65,7 @@ known_standard_library =
     collections,copy,distutils,functools,inspect,io,json,logging,operator,os,pkg_resources,re,setuptools,sys,
     types,warnings
 known_third_party =
-    coreapi,coreschema,datadiff,dj_database_url,django,django_filters,djangorestframework_camel_case,flex,gunicorn,
-    inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm,swagger_spec_validator,uritemplate,user_agents,
-    whitenoise
-known_first_party = drf_yasg,testproj,articles,snippets,users,urlconfs
+    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
+known_first_party = drf_yasg,testproj,articles,people,snippets,todo,users,urlconfs

update-ui.sh

@@ -2,7 +2,7 @@
 set -ev
 npm update
 
-cp node_modules/redoc/dist/redoc.min.js src/drf_yasg/static/drf-yasg/redoc/
+cp node_modules/redoc/bundles/redoc.standalone.js src/drf_yasg/static/drf-yasg/redoc/redoc.min.js
 cp -r node_modules/swagger-ui-dist src/drf_yasg/static/drf-yasg/
 pushd src/drf_yasg/static/drf-yasg/swagger-ui-dist/ >/dev/null
 rm -f package.json .npmignore README.md