Update changelog

* Move add_manual_fields call to make_schema_definition
* Do not call add_manual_fields twice

.travis.yml

@@ -2,7 +2,6 @@ language: python
 cache: pip
 
 python:
- - '2.7'
  - '3.4'
  - '3.5'
  - '3.6'
@@ -14,6 +13,9 @@ env:
 jobs:
   include:
     - stage: test
+      python: '2.7'
+      env: DRF=3.7
+    -
       python: '3.6'
       env: DRF=master
     -

CONTRIBUTING.rst

@@ -36,7 +36,7 @@ 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 -rrequirements/dev.txt "Django>=1.11.7"
+      (venv) $ pip install -r requirements/dev.txt
 
 #. **Make your changes and check them against the test project**
 

README.rst

@@ -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,85 @@ Changelog
 #########
 
 
+*********
+**1.9.0**
+*********
+
+*Release date: Jun 16, 2018*
+
+- **ADDED:** added ``DEFAULT_GENERATOR_CLASS`` setting and ``--generator-clas`` 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 crash when encountering ``coreapi.Fields``\ s without a ``schema`` (:issue:`143`)
+
+
+*********
+**1.8.0**
+*********
+
+*Release date: Jun 01, 2018*
+
+- **ADDED:** added a :ref:`swagger_schema_fields <swagger_schema_fields>` field on serializer ``Meta`` classes for
+  customizing schema generation (:issue:`132`, :pr:`134`)
+- **FIXED:** error responses from schema views are now rendered with ``JSONRenderer`` instead of throwing
+  confusing errors (:pr:`130`, :issue:`58`)
+- **FIXED:** ``readOnly`` schema fields will now no longer be marked as ``required`` (:pr:`133`)
+
+*********
+**1.7.4**
+*********
+
+*Release date: May 14, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.14.2
+- **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.20
+- **FIXED:** ignore ``None`` return from ``get_operation`` to avoid empty ``Path`` objects in output
+- **FIXED:** request body is now allowed on ``DELETE`` endpoints (:issue:`118`)
+
+*********
+**1.7.3**
+*********
+
+*Release date: May 12, 2018*
+
+- **FIXED:** views whose ``__init__`` methods throw exceptions will now be ignored during endpoint enumeration
+
+*********
+**1.7.2**
+*********
+
+*Release date: May 12, 2018*
+
+- **FIXED:** fixed generation of default ``SECURITY_REQUIREMENTS`` to match documented behaviour
+- **FIXED:** ordering of ``SECURITY_REQUIREMENTS`` and ``SECURITY_DEFINITIONS`` is now stable
+
+*********
+**1.7.1**
+*********
+
+*Release date: May 05, 2018*
+
+- **IMPROVED:** updated ``swagger-ui`` to version 3.14.1
+- **IMPROVED:** set ``swagger-ui`` ``showCommonExtensions`` to ``True`` by default and add
+  ``SHOW_COMMON_EXTENSIONS`` setting key
+- **IMPROVED:** set ``min_length=1`` when ``allow_blank=False`` (:pr:`112`, thanks to :ghuser:`elnappo`)
+- **FIXED:** made documentation ordering of ``SwaggerDict`` extra attributes stable
+
+*********
+**1.7.0**
+*********
+
+*Release date: Apr 27, 2018*
+
+- **ADDED:** added integration with `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_
+  (:issue:`109`, :pr:`110`, thanks to :ghuser:`rsichny`)
+
+  *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.RecursiveFieldInspector`` to
+  your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value
+
+- **FIXED:** ``SchemaRef`` now supports cyclical references via the ``ignore_unresolved`` argument
+
 *********
 **1.6.2**
 *********

docs/custom_spec.rst

@@ -169,13 +169,19 @@ You can define some per-serializer options by adding a ``Meta`` class to your se
       class Meta:
          ... options here ...
 
-Currently, the only option you can add here is
+.. _swagger_schema_fields:
+
+The available options are:
 
    * ``ref_name`` - a string which will be used as the model definition name for this serializer class; setting it to
      ``None`` will force the serializer to be generated as an inline model everywhere it is used. If two serializers
      have the same ``ref_name``, both their usages will be replaced with a reference to the same definition.
      If this option is not specified, all serializers have an implicit name derived from their class name, minus any
      ``Serializer`` suffix (e.g. ``UserSerializer`` -> ``User``, ``SerializerWithSuffix`` -> ``SerializerWithSuffix``)
+   * ``swagger_schema_fields`` - a dictionary mapping :class:`.Schema` field names to values. These attributes
+     will be set on the :class:`.Schema` object generated from the ``Serializer``. Field names must be python values,
+     which are converted to Swagger ``Schema`` attribute names according to :func:`.make_swagger_name`.
+     Attribute names and values must conform to the `OpenAPI 2.0 specification <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject>`_.
 
 
 *************************

docs/security.rst

@@ -39,7 +39,7 @@ Security requirements
 The second step is specifying, for each endpoint, which authentication mechanism can be used for interacting with it.
 See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object for details.
 
-By default, a top-level `security` that accepts all the declared security definitions is generated.
+By default, a top-level `security` that accepts any one of the declared security definitions is generated.
 For the example above, that would be :code:`[{'Basic': []}, {'Bearer': []}]`. This can be overriden using the
 :ref:`SECURITY_REQUIREMENTS <security-definitions-settings>` setting.
 

docs/settings.rst

@@ -43,6 +43,14 @@ The possible settings and their default values are as follows:
 Default classes
 ===============
 
+DEFAULT_GENERATOR_CLASS
+-------------------------
+
+:class:`~.generators.OpenAPISchemaGenerator` subclass that will be used by default for generating the final
+:class:`.Schema` object. Can be overriden by the ``generator_class`` argument to :func:`.get_schema_view`.
+
+**Default**: :class:`drf_yasg.generators.OpenAPISchemaGenerator`
+
 DEFAULT_AUTO_SCHEMA_CLASS
 -------------------------
 
@@ -67,6 +75,7 @@ to this list.
 :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| \
 ``]``
@@ -101,7 +110,7 @@ DEFAULT_INFO
 ------------
 
 An import string to an :class:`.openapi.Info` object. This will be used when running the ``generate_swagger``
-management command, or if no ``info`` argument is passed to ``get_schema_view``.
+management command, or if no ``info`` argument is passed to :func:`.get_schema_view`.
 
 **Default**: :python:`None`
 
@@ -254,6 +263,15 @@ Controls how many levels are expaned by default when showing nested models.
 **Default**: :python:`3` |br|
 *Maps to parameter*: ``defaultModelExpandDepth``
 
+DEFAULT_MODEL_DEPTH
+-------------------
+
+Controls the display of extensions (``pattern``, ``maxLength``, ``minLength``, ``maximum``, ```minimum``) fields and
+values for Parameters.
+
+**Default**: :python:`True` |br|
+*Maps to parameter*: ``showCommonExtensions``
+
 .. _oauth2-settings:
 
 OAUTH2_REDIRECT_URL

package.json

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

requirements/base.txt

@@ -8,5 +8,4 @@ six>=1.10.0
 uritemplate>=3.0.0
 
 djangorestframework>=3.7.7
-Django>=1.11.7,<2.0; python_version <= "2.7"
+Django>=1.11.7
-Django>=1.11.7; python_version >= "3.4"

requirements/test.txt

@@ -3,8 +3,7 @@ pytest>=2.9
 pytest-pythonpath>=0.7.1
 pytest-cov>=2.5.1
 pytest-xdist>=1.22.0
-# latest pip version of pytest-django is more than a year old and does not support Django 2.0
+pytest-django>=3.2.0
-git+https://github.com/pytest-dev/pytest-django.git@94cccb956435dd7a719606744ee7608397e1eafb
 datadiff==2.0.0
 
 -r testproj.txt

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

src/drf_yasg/app_settings.py

@@ -2,16 +2,18 @@ from django.conf import settings
 from rest_framework.settings import perform_import
 
 SWAGGER_DEFAULTS = {
+    'DEFAULT_GENERATOR_CLASS': 'drf_yasg.generators.OpenAPISchemaGenerator',
     'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
 
     'DEFAULT_FIELD_INSPECTORS': [
         'drf_yasg.inspectors.CamelCaseJSONFilter',
+        'drf_yasg.inspectors.RecursiveFieldInspector',
         'drf_yasg.inspectors.ReferencingSerializerInspector',
-        'drf_yasg.inspectors.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',
     ],
@@ -44,6 +46,7 @@ SWAGGER_DEFAULTS = {
     'SHOW_EXTENSIONS': True,
     'DEFAULT_MODEL_RENDERING': 'model',
     'DEFAULT_MODEL_DEPTH': 3,
+    'SHOW_COMMON_EXTENSIONS': True,
     'OAUTH2_REDIRECT_URL': None,
     'OAUTH2_CONFIG': {},
     'SUPPORTED_SUBMIT_METHODS': [
@@ -66,6 +69,7 @@ REDOC_DEFAULTS = {
 }
 
 IMPORT_STRINGS = [
+    'DEFAULT_GENERATOR_CLASS',
     'DEFAULT_AUTO_SCHEMA_CLASS',
     'DEFAULT_FIELD_INSPECTORS',
     'DEFAULT_FILTER_INSPECTORS',

src/drf_yasg/generators.py

@@ -86,14 +86,17 @@ class EndpointEnumerator(_EndpointEnumerator):
         for pattern in patterns:
             path_regex = prefix + get_original_route(pattern)
             if isinstance(pattern, URLPattern):
-                path = self.get_path_from_regex(path_regex)
+                try:
-                callback = pattern.callback
+                    path = self.get_path_from_regex(path_regex)
-                url_name = pattern.name
+                    callback = pattern.callback
-                if self.should_include_endpoint(path, callback, app_name or '', namespace or '', url_name):
+                    url_name = pattern.name
-                    path = self.replace_version(path, callback)
+                    if self.should_include_endpoint(path, callback, app_name or '', namespace or '', url_name):
-                    for method in self.get_allowed_methods(callback):
+                        path = self.replace_version(path, callback)
-                        endpoint = (path, method, callback)
+                        for method in self.get_allowed_methods(callback):
-                        api_endpoints.append(endpoint)
+                            endpoint = (path, method, callback)
+                            api_endpoints.append(endpoint)
+                except Exception:  # pragma: no cover
+                    logger.warning('failed to enumerate view', exc_info=True)
 
             elif isinstance(pattern, URLResolver):
                 nested_endpoints = self.get_api_endpoints(
@@ -204,9 +207,15 @@ class OpenAPISchemaGenerator(object):
         paths, prefix = self.get_paths(endpoints, components, request, public)
 
         security_definitions = swagger_settings.SECURITY_DEFINITIONS
+        if security_definitions is not None:
+            security_definitions = OrderedDict(sorted([(key, OrderedDict(sorted(sd.items())))
+                                                       for key, sd in swagger_settings.SECURITY_DEFINITIONS.items()]))
         security_requirements = swagger_settings.SECURITY_REQUIREMENTS
         if security_requirements is None:
-            security_requirements = [{security_scheme: [] for security_scheme in swagger_settings.SECURITY_DEFINITIONS}]
+            security_requirements = [{security_scheme: []} for security_scheme in swagger_settings.SECURITY_DEFINITIONS]
+
+        security_requirements = sorted(security_requirements, key=lambda od: list(sorted(od)))
+        security_requirements = [OrderedDict(sorted(sr.items())) for sr in security_requirements]
 
         url = self.url
         if url is None and request is not None:
@@ -315,7 +324,9 @@ class OpenAPISchemaGenerator(object):
                 if not public and not self._gen.has_view_permissions(path, method, view):
                     continue
 
-                operations[method.lower()] = self.get_operation(view, path, prefix, method, components, request)
+                operation = self.get_operation(view, path, prefix, method, components, request)
+                if operation is not None:
+                    operations[method.lower()] = operation
 
             if operations:
                 # since the common prefix is used as the API basePath, it must be stripped
@@ -356,6 +367,9 @@ class OpenAPISchemaGenerator(object):
 
         view_inspector = view_inspector_cls(view, path, method, components, request, overrides)
         operation = view_inspector.get_operation(operation_keys)
+        if operation is None:
+            return None
+
         if 'consumes' in operation and set(operation.consumes) == set(self.consumes):
             del operation.consumes
         if 'produces' in operation and set(operation.produces) == set(self.produces):
@@ -401,7 +415,6 @@ class OpenAPISchemaGenerator(object):
         """
         parameters = []
         queryset = getattr(view_cls, 'queryset', None)
-        model = getattr(getattr(view_cls, 'queryset', None), 'model', None)
 
         for variable in sorted(uritemplate.variables(path)):
             model, model_field = get_queryset_field(queryset, variable)

src/drf_yasg/inspectors/__init__.py

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

src/drf_yasg/inspectors/base.py

@@ -276,7 +276,10 @@ class SerializerInspector(FieldInspector):
 
 
 class ViewInspector(BaseInspector):
-    body_methods = ('PUT', 'PATCH', 'POST')  #: methods that are allowed to have a request body
+    body_methods = ('PUT', 'PATCH', 'POST', 'DELETE')  #: methods that are allowed to have a request body
+
+    #: methods that are assumed to require a request body determined by the view's ``serializer_class``
+    implicit_body_methods = ('PUT', 'PATCH', 'POST')
 
     # real values set in __init__ to prevent import errors
     field_inspectors = []  #:

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__)
@@ -22,12 +22,36 @@ 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)
 
+    def add_manual_parameters(self, serializer, parameters):
+        """Add/replace parameters from the given list of automatically generated request parameters. This method
+        is called only when the serializer is converted into a list of parameters for use in a form data request.
+
+        :param serializer: serializer instance
+        :param list[openapi.Parameter] parameters: genereated parameters
+        :return: modified parameters
+        :rtype: list[openapi.Parameter]
+        """
+        return parameters
+
     def get_request_parameters(self, serializer, in_):
         fields = getattr(serializer, 'fields', {})
-        return [
+        parameters = [
             self.probe_field_inspectors(
                 value, openapi.Parameter, self.use_definitions,
                 name=self.get_parameter_name(key), in_=in_
@@ -36,12 +60,17 @@ class InlineSerializerInspector(SerializerInspector):
             in fields.items()
         ]
 
+        return self.add_manual_parameters(serializer, parameters)
+
     def get_property_name(self, field_name):
         return field_name
 
     def get_parameter_name(self, field_name):
         return field_name
 
+    def get_serializer_ref_name(self, serializer):
+        return get_serializer_ref_name(serializer)
+
     def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
         SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type, use_references, **kwargs)
 
@@ -55,33 +84,24 @@ class InlineSerializerInspector(SerializerInspector):
             if swagger_object_type != openapi.Schema:
                 raise SwaggerGenerationError("cannot instantiate nested serializer as " + swagger_object_type.__name__)
 
-            serializer = field
+            ref_name = self.get_serializer_ref_name(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')]
 
             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
+                        'read_only': bool(child.read_only) or None
                     }
                     prop_kwargs = filter_none(prop_kwargs)
 
-                    properties[property_name] = self.probe_field_inspectors(
+                    child_schema = self.probe_field_inspectors(
                         child, ChildSwaggerType, use_references, **prop_kwargs
                     )
-                    if child.required:
+                    properties[property_name] = child_schema
+
+                    if child.required and not getattr(child_schema, 'read_only', False):
                         required.append(property_name)
 
                 result = SwaggerType(
@@ -94,6 +114,10 @@ class InlineSerializerInspector(SerializerInspector):
                     # but is visually 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:
@@ -292,6 +316,10 @@ def find_limits(field):
                 if attr not in limits or improves(limit_value, limits[attr]):
                     limits[attr] = limit_value
 
+    if hasattr(field, "allow_blank") and not field.allow_blank:
+        if limits.get('min_length', 0) < 1:
+            limits['min_length'] = 1
+
     return OrderedDict(sorted(limits.items()))
 
 
@@ -531,3 +559,24 @@ else:
                 return camelize_schema(result, self.components)
 
             return result
+
+try:
+    from rest_framework_recursive.fields import RecursiveField
+except ImportError:  # pragma: no cover
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+        pass
+else:
+    class RecursiveFieldInspector(FieldInspector):
+        """Provides conversion for RecursiveField (https://github.com/heywbj/django-rest-framework-recursive)"""
+        def field_to_swagger_object(self, field, swagger_object_type, use_references, **kwargs):
+            if isinstance(field, RecursiveField) and swagger_object_type == openapi.Schema:
+                assert use_references is True, "Can not create schema for RecursiveField when use_references is False"
+
+                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/inspectors/query.py

@@ -48,7 +48,7 @@ class CoreAPICompatInspector(PaginatorInspector, FilterInspector):
             in_=location_to_in[field.location],
             type=coreapi_types.get(type(field.schema), openapi.TYPE_STRING),
             required=field.required,
-            description=field.schema.description,
+            description=field.schema.description if field.schema else None,
         )
 
 
@@ -70,7 +70,10 @@ class DjangoRestResponsePagination(PaginatorInspector):
                     ('previous', openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_URI)),
                     ('results', response_schema),
                 )),
-                required=['count', 'results']
+                required=['results']
             )
 
+            if has_count:
+                paged_schema.required.insert(0, 'count')
+
         return paged_schema

src/drf_yasg/inspectors/view.py

@@ -1,3 +1,4 @@
+import logging
 from collections import OrderedDict
 
 from rest_framework.request import is_form_media_type
@@ -12,6 +13,8 @@ from ..utils import (
 )
 from .base import ViewInspector
 
+log = logging.getLogger(__name__)
+
 
 class SwaggerAutoSchema(ViewInspector):
     def __init__(self, view, path, method, components, request, overrides):
@@ -83,7 +86,11 @@ class SwaggerAutoSchema(ViewInspector):
         """
         if not hasattr(self.view, 'get_serializer'):
             return None
-        return self.view.get_serializer()
+        try:
+            return self.view.get_serializer()
+        except Exception:
+            log.warning("view's get_serializer raised exception (%s)", type(self.view).__name__, exc_info=True)
+            return None
 
     def get_request_serializer(self):
         """Return the request serializer (used for parsing the request payload) for this endpoint.
@@ -101,7 +108,7 @@ class SwaggerAutoSchema(ViewInspector):
             if isinstance(body_override, openapi.Schema.OR_REF):
                 return body_override
             return force_serializer_instance(body_override)
-        elif self.method in self.body_methods:
+        elif self.method in self.implicit_body_methods:
             return self.get_view_serializer()
 
         return None
@@ -144,8 +151,11 @@ class SwaggerAutoSchema(ViewInspector):
             raise SwaggerGenerationError("specify the body parameter as a Schema or Serializer in request_body")
         if any(param.in_ == openapi.IN_FORM for param in manual_parameters):  # pragma: no cover
             if any(param.in_ == openapi.IN_BODY for param in parameters.values()):
-                raise SwaggerGenerationError("cannot add form parameters when the request has a request schema; "
+                raise SwaggerGenerationError("cannot add form parameters when the request has a request body; "
                                              "did you forget to set an appropriate parser class on the view?")
+            if self.method not in self.body_methods:
+                raise SwaggerGenerationError("form parameters can only be applied to (" + ','.join(self.body_methods) +
+                                             ") HTTP methods")
 
         parameters.update(param_list_to_odict(manual_parameters))
         return list(parameters.values())

src/drf_yasg/management/commands/generate_swagger.py

@@ -2,6 +2,7 @@ import json
 import logging
 import os
 from collections import OrderedDict
+from importlib import import_module
 
 from django.contrib.auth.models import User
 from django.core.exceptions import ImproperlyConfigured
@@ -12,7 +13,15 @@ from rest_framework.views import APIView
 from ... import openapi
 from ...app_settings import swagger_settings
 from ...codecs import OpenAPICodecJson, OpenAPICodecYaml
-from ...generators import OpenAPISchemaGenerator
+
+
+def import_class(import_string):
+    if not import_string:
+        return None
+
+    module_path, class_name = import_string.rsplit('.', 1)
+    module = import_module(module_path)
+    return getattr(module, class_name)
 
 
 class Command(BaseCommand):
@@ -64,6 +73,11 @@ class Command(BaseCommand):
                  'OpenAPISchemaGenerator.get_schema().\n'
                  'This option implies --mock-request.'
         )
+        parser.add_argument(
+            '-g', '--generator-class', dest='generator_class_name',
+            default='',
+            help='Import string pointing to an OpenAPISchemaGenerator subclass to use for schema generation.'
+        )
 
     def write_schema(self, schema, stream, format):
         if format == 'json':
@@ -89,7 +103,8 @@ class Command(BaseCommand):
         request = APIView().initialize_request(request)
         return request
 
-    def handle(self, output_file, overwrite, format, api_url, mock, user, private, *args, **options):
+    def handle(self, output_file, overwrite, format, api_url, mock, user, private, generator_class_name,
+               *args, **kwargs):
         # disable logs of WARNING and below
         logging.disable(logging.WARNING)
 
@@ -117,7 +132,8 @@ class Command(BaseCommand):
 
         request = self.get_mock_request(api_url, format, user) if mock else None
 
-        generator = OpenAPISchemaGenerator(
+        generator_class = import_class(generator_class_name) or swagger_settings.DEFAULT_GENERATOR_CLASS
+        generator = generator_class(
             info=info,
             url=api_url
         )

src/drf_yasg/openapi.py

@@ -116,7 +116,7 @@ class SwaggerDict(OrderedDict):
         which would result in the extra attributes being added first. For this reason, we defer the insertion of the
         attributes and require that subclasses call ._insert_extras__ at the end of their __init__ method.
         """
-        for attr, val in self._extras__.items():
+        for attr, val in sorted(self._extras__.items()):
             setattr(self, attr, val)
 
     @staticmethod
@@ -221,7 +221,7 @@ class Swagger(SwaggerDict):
         :param str _prefix: api path prefix to use in setting basePath; this will be appended to the wsgi
             SCRIPT_NAME prefix or Django's FORCE_SCRIPT_NAME if applicable
         :param str _version: version string to override Info
-        :param list[dict] security_definitions: list of supported authentication mechanisms
+        :param dict[str,dict[str,str]] security_definitions: list of supported authentication mechanisms
         :param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation
         :param list[str] consumes: consumed MIME types; can be overriden in Operation
         :param list[str] produces: produced MIME types; can be overriden in Operation
@@ -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)
+        if not ignore_unresolved:
-        assert isinstance(obj, expected_type), ref_name + " is a {actual}, not a {expected}" \
+            obj = resolver.get(name, scope)
-            .format(actual=type(obj).__name__, expected=expected_type.__name__)
+            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

@@ -1,5 +1,5 @@
 from django.shortcuts import render, resolve_url
-from rest_framework.renderers import BaseRenderer, TemplateHTMLRenderer
+from rest_framework.renderers import BaseRenderer, JSONRenderer, TemplateHTMLRenderer
 from rest_framework.utils import json
 
 from drf_yasg.openapi import Swagger
@@ -10,7 +10,7 @@ from .codecs import VALIDATORS, OpenAPICodecJson, OpenAPICodecYaml
 
 class _SpecRenderer(BaseRenderer):
     """Base class for text renderers. Handles encoding and validation."""
-    charset = None
+    charset = 'utf-8'
     validators = []
     codec_class = None
 
@@ -22,6 +22,12 @@ class _SpecRenderer(BaseRenderer):
     def render(self, data, media_type=None, renderer_context=None):
         assert self.codec_class, "must override codec_class"
         codec = self.codec_class(self.validators)
+
+        if not isinstance(data, Swagger):  # pragma: no cover
+            # if `swagger` is not a ``Swagger`` object, it means we somehow got a non-success ``Response``
+            # in that case, it's probably better to let the default ``TemplateHTMLRenderer`` render it
+            # see https://github.com/axnsan12/drf-yasg/issues/58
+            return JSONRenderer().render(data, media_type, renderer_context)
         return codec.encode(data)
 
 
@@ -53,7 +59,7 @@ class _UIRenderer(BaseRenderer):
     template = ''
 
     def render(self, swagger, accepted_media_type=None, renderer_context=None):
-        if not isinstance(swagger, Swagger):
+        if not isinstance(swagger, Swagger):  # pragma: no cover
             # if `swagger` is not a ``Swagger`` object, it means we somehow got a non-success ``Response``
             # in that case, it's probably better to let the default ``TemplateHTMLRenderer`` render it
             # see https://github.com/axnsan12/drf-yasg/issues/58
@@ -93,6 +99,7 @@ class _UIRenderer(BaseRenderer):
             'defaultModelRendering': swagger_settings.DEFAULT_MODEL_RENDERING,
             'defaultModelExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
             'defaultModelsExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH,
+            'showCommonExtensions': swagger_settings.SHOW_COMMON_EXTENSIONS,
             'oauth2RedirectUrl': swagger_settings.OAUTH2_REDIRECT_URL,
             'supportedSubmitMethods': swagger_settings.SUPPORTED_SUBMIT_METHODS,
         }

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/utils.py

@@ -66,7 +66,7 @@ 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 security: security requirements override; used to specify which authetication mechanism
+    :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 dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: a dict of documented manual responses
@@ -295,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

@@ -11,7 +11,6 @@ from rest_framework.settings import api_settings
 from rest_framework.views import APIView
 
 from .app_settings import swagger_settings
-from .generators import OpenAPISchemaGenerator
 from .renderers import OpenAPIRenderer, ReDocRenderer, SwaggerJSONRenderer, SwaggerUIRenderer, SwaggerYAMLRenderer
 
 SPEC_RENDERERS = (SwaggerYAMLRenderer, SwaggerJSONRenderer, OpenAPIRenderer)
@@ -46,7 +45,7 @@ def deferred_never_cache(view_func):
 
 
 def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=False, validators=None,
-                    generator_class=OpenAPISchemaGenerator,
+                    generator_class=swagger_settings.DEFAULT_GENERATOR_CLASS,
                     authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
                     permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
     """Create a SchemaView class with default renderers and generators.

testproj/articles/serializers.py

@@ -11,7 +11,7 @@ class ArticleSerializer(serializers.ModelSerializer):
         read_only=True,
     )
     uuid = serializers.UUIDField(help_text="should articles have UUIDs?", read_only=True)
-    cover_name = serializers.FileField(use_url=False, source='cover', read_only=True)
+    cover_name = serializers.FileField(use_url=False, source='cover', required=True)
     group = serializers.SlugRelatedField(slug_field='uuid', queryset=ArticleGroup.objects.all())
     original_group = serializers.SlugRelatedField(slug_field='uuid', read_only=True)
 

testproj/snippets/views.py

@@ -33,6 +33,21 @@ class SnippetList(generics.ListCreateAPIView):
         """post method docstring"""
         return super(SnippetList, self).post(request, *args, **kwargs)
 
+    @swagger_auto_schema(
+        operation_id='snippets_delete_bulk',
+        request_body=openapi.Schema(
+            type=openapi.TYPE_OBJECT,
+            properties={
+                'body': openapi.Schema(
+                    type=openapi.TYPE_STRING,
+                    description='this should not crash (request body on DELETE method)'
+                )
+            }
+        ),
+    )
+    def delete(self, *args, **kwargs):
+        pass
+
 
 class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
     """
@@ -56,18 +71,26 @@ class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
         """patch method docstring"""
         return super(SnippetDetail, self).patch(request, *args, **kwargs)
 
-    @swagger_auto_schema(manual_parameters=[
+    @swagger_auto_schema(
-        openapi.Parameter(
+        manual_parameters=[
-            name='id', in_=openapi.IN_PATH,
+            openapi.Parameter(
-            type=openapi.TYPE_INTEGER,
+                name='id', in_=openapi.IN_PATH,
-            description="path parameter override",
+                type=openapi.TYPE_INTEGER,
-            required=True
+                description="path parameter override",
-        ),
+                required=True
-    ], responses={
+            ),
-        status.HTTP_204_NO_CONTENT: openapi.Response(
+            openapi.Parameter(
-            description="This should not crash"
+                name='delete_form_param', in_=openapi.IN_FORM,
-        )
+                type=openapi.TYPE_INTEGER,
-    })
+                description="this should not crash (form parameter on DELETE method)"
+            ),
+        ],
+        responses={
+            status.HTTP_204_NO_CONTENT: openapi.Response(
+                description="this should not crash (response object with no schema)"
+            )
+        }
+    )
     def delete(self, request, *args, **kwargs):
         """delete method docstring"""
         return super(SnippetDetail, self).patch(request, *args, **kwargs)

testproj/testproj/settings/base.py

@@ -94,7 +94,18 @@ SWAGGER_SETTINGS = {
     'LOGIN_URL': '/admin/login',
     'LOGOUT_URL': '/admin/logout',
 
-    'DEFAULT_INFO': 'testproj.urls.swagger_info'
+    'DEFAULT_INFO': 'testproj.urls.swagger_info',
+
+    'SECURITY_DEFINITIONS': {
+        'Basic': {
+            'type': 'basic'
+        },
+        'Bearer': {
+            'type': 'apiKey',
+            'name': 'Authorization',
+            'in': 'header'
+        }
+    }
 }
 
 # Internationalization

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,7 +1,10 @@
+from collections import OrderedDict
+
 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):
@@ -25,3 +28,31 @@ class TodoYetAnotherSerializer(serializers.ModelSerializer):
         model = TodoYetAnother
         fields = ('title', 'todo')
         depth = 2
+        swagger_schema_fields = {
+            'example': OrderedDict([
+                ('title', 'parent'),
+                ('todo', OrderedDict([
+                    ('title', 'child'),
+                    ('todo', None),
+                ])),
+            ])
+        }
+
+
+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

@@ -7,10 +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+)/$',
+    url(r'^(?P<todo_id>\d+)/yetanothers/(?P<yetanother_id>\d+)/$',
-        views.NestedTodoView.as_view(),),
+        views.NestedTodoView.as_view(), ),
 ]

testproj/todo/views.py

@@ -1,8 +1,10 @@
 from rest_framework import viewsets
 from rest_framework.generics import RetrieveAPIView
 
-from .models import Todo, TodoAnother, TodoYetAnother
+from .models import Todo, TodoAnother, TodoTree, TodoYetAnother
-from .serializer import TodoAnotherSerializer, TodoSerializer, TodoYetAnotherSerializer
+from .serializer import (
+    TodoAnotherSerializer, TodoRecursiveSerializer, TodoSerializer, TodoTreeSerializer, TodoYetAnotherSerializer
+)
 
 
 class TodoViewSet(viewsets.ReadOnlyModelViewSet):
@@ -25,3 +27,13 @@ class TodoYetAnotherViewSet(viewsets.ReadOnlyModelViewSet):
 
 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

@@ -21,10 +21,15 @@ consumes:
 produces:
   - application/json
 securityDefinitions:
-  basic:
+  Basic:
     type: basic
+  Bearer:
+    in: header
+    name: Authorization
+    type: apiKey
 security:
-  - basic: []
+  - Basic: []
+  - Bearer: []
 paths:
   /articles/:
     get:
@@ -202,6 +207,7 @@ paths:
           type: string
           pattern: ^69$
           default: '69'
+          minLength: 1
         - name: image_styles
           in: formData
           description: Parameter with Items
@@ -382,6 +388,24 @@ paths:
             $ref: '#/definitions/Snippet'
       tags:
         - snippets
+    delete:
+      operationId: snippetsDeleteBulk
+      description: SnippetList classdoc
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            type: object
+            properties:
+              body:
+                description: this should not crash (request body on DELETE method)
+                type: string
+      responses:
+        '204':
+          description: ''
+      tags:
+        - snippets
     parameters: []
   /snippets/{id}/:
     get:
@@ -436,9 +460,13 @@ paths:
           description: path parameter override
           required: true
           type: integer
+        - name: delete_form_param
+          in: formData
+          description: this should not crash (form parameter on DELETE method)
+          type: integer
       responses:
         '204':
-          description: This should not crash
+          description: this should not crash (response object with no schema)
       tags:
         - snippets
     parameters:
@@ -495,6 +523,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
@@ -546,9 +697,9 @@ paths:
         description: A unique integer value identifying this todo.
         required: true
         type: integer
-  /todo/{todo_id}/yetanother/{yetanother_id}/:
+  /todo/{todo_id}/yetanothers/{yetanother_id}/:
     get:
-      operationId: todo_yetanother_read
+      operationId: todo_yetanothers_read
       description: ''
       parameters: []
       responses:
@@ -577,6 +728,7 @@ paths:
           description: this field is generated from a query_serializer
           required: false
           type: string
+          minLength: 1
         - name: is_staff
           in: query
           description: this one too!
@@ -677,6 +829,7 @@ definitions:
         description: title model help_text
         type: string
         maxLength: 255
+        minLength: 1
       author:
         description: The ID of the user that created this article; if none is provided,
           defaults to the currently logged in user.
@@ -686,6 +839,7 @@ definitions:
         description: body serializer help_text
         type: string
         maxLength: 5000
+        minLength: 1
       slug:
         description: slug model help_text
         type: string
@@ -707,6 +861,7 @@ definitions:
           description: but i needed to test these 2 fields somehow
           type: string
           format: uri
+          minLength: 1
         readOnly: true
       uuid:
         description: should articles have UUIDs?
@@ -749,10 +904,12 @@ definitions:
         title: FirstName
         type: string
         maxLength: 30
+        minLength: 1
       lastName:
         title: LastName
         type: string
         maxLength: 30
+        minLength: 1
   Person:
     required:
       - identity
@@ -774,10 +931,12 @@ definitions:
         title: Project name
         description: Name of the project
         type: string
+        minLength: 1
       githubRepo:
         title: Github repo
         description: Github repository of the project
         type: string
+        minLength: 1
   Snippet:
     required:
       - code
@@ -799,6 +958,7 @@ definitions:
         description: The ID of the user that created this snippet.
         type: string
         readOnly: true
+        minLength: 1
         title: Owner as string
       title:
         title: Title
@@ -807,6 +967,7 @@ definitions:
       code:
         title: Code
         type: string
+        minLength: 1
       linenos:
         title: Linenos
         type: boolean
@@ -1325,6 +1486,7 @@ definitions:
         title: Title
         type: string
         maxLength: 50
+        minLength: 1
   TodoAnother:
     required:
       - title
@@ -1335,8 +1497,47 @@ definitions:
         title: Title
         type: string
         maxLength: 50
+        minLength: 1
       todo:
         $ref: '#/definitions/Todo'
+  TodoRecursive:
+    required:
+      - title
+    type: object
+    properties:
+      id:
+        title: ID
+        type: integer
+        readOnly: true
+      title:
+        title: Title
+        type: string
+        maxLength: 50
+        minLength: 1
+      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
+        minLength: 1
+      children:
+        type: array
+        items:
+          $ref: '#/definitions/TodoTree'
   TodoYetAnother:
     required:
       - title
@@ -1346,6 +1547,7 @@ definitions:
         title: Title
         type: string
         maxLength: 50
+        minLength: 1
       todo:
         required:
           - title
@@ -1359,6 +1561,7 @@ definitions:
             title: Title
             type: string
             maxLength: 50
+            minLength: 1
           todo:
             required:
               - title
@@ -1372,8 +1575,14 @@ definitions:
                 title: Title
                 type: string
                 maxLength: 50
+                minLength: 1
             readOnly: true
         readOnly: true
+    example:
+      title: parent
+      todo:
+        title: child
+        todo: null
   UserSerializerrr:
     required:
       - username
@@ -1392,6 +1601,7 @@ definitions:
         type: string
         pattern: ^[\w.@+-]+$
         maxLength: 150
+        minLength: 1
       email:
         title: Email address
         type: string
@@ -1413,6 +1623,7 @@ definitions:
         type: string
         format: ipv4
         readOnly: true
+        minLength: 1
       last_connected_at:
         title: Last connected at
         description: really?

tests/test_management.py

@@ -11,17 +11,18 @@ import pytest
 from django.contrib.auth.models import User
 from django.core.management import call_command
 
+from drf_yasg import openapi
 from drf_yasg.codecs import yaml_sane_load
+from drf_yasg.generators import OpenAPISchemaGenerator
 
 
 def call_generate_swagger(output_file='-', overwrite=False, format='', api_url='',
-                          mock=False, user='', private=False, **kwargs):
+                          mock=False, user='', private=False, generator_class_name='', **kwargs):
     out = StringIO()
     call_command(
         'generate_swagger', stdout=out,
-        output_file=output_file, overwrite=overwrite, format=format,
+        output_file=output_file, overwrite=overwrite, format=format, api_url=api_url, mock=mock, user=user,
-        api_url=api_url, mock=mock, user=user, private=private,
+        private=private, generator_class_name=generator_class_name, **kwargs
-        **kwargs
     )
     return out.getvalue()
 
@@ -46,6 +47,17 @@ def test_no_mock(db):
     assert len(output_schema['paths']) > 0
 
 
+class EmptySchemaGenerator(OpenAPISchemaGenerator):
+    def get_paths(self, endpoints, components, request, public):
+        return openapi.Paths(paths={}), ''
+
+
+def test_generator_class(db):
+    output = call_generate_swagger(generator_class_name='test_management.EmptySchemaGenerator')
+    output_schema = json.loads(output, object_pairs_hook=OrderedDict)
+    assert len(output_schema['paths']) == 0
+
+
 def silentremove(filename):
     try:
         os.remove(filename)

tests/test_swaggerdict.py

@@ -1,3 +1,6 @@
+from collections import OrderedDict
+from random import shuffle
+
 from drf_yasg import openapi
 
 
@@ -51,3 +54,15 @@ def test_trailing_underscore_stripped():
     del sd.in_
     assert 'in' not in sd
     assert not hasattr(sd, 'in__')
+
+
+def test_extra_ordering():
+    """Insertion order should also be consistent when setting undeclared parameters (kwargs) in SwaggerDict"""
+    extras = [('beta', 1), ('alpha', 2), ('omega', 3), ('gamma', 4)]
+    shuffled_extras = list(extras)
+    shuffle(shuffled_extras)
+
+    s1 = openapi.SwaggerDict(**OrderedDict(extras))
+    s2 = openapi.SwaggerDict(**OrderedDict(shuffled_extras))
+
+    assert list(s1.items()) == list(s2.items())

tox.ini

@@ -46,7 +46,7 @@ commands =
 [pytest]
 DJANGO_SETTINGS_MODULE = testproj.settings.local
 python_paths = testproj
-addopts = -n 3
+addopts = -n 3 --ignore=node_modules
 
 [flake8]
 max-line-length = 120
@@ -65,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,
+    coreapi,coreschema,datadiff,dj_database_url,django,django_filters,djangorestframework_camel_case,
-    inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm,swagger_spec_validator,uritemplate,user_agents,
+    rest_framework_recursive,flex,gunicorn,inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm,
-    whitenoise
+    swagger_spec_validator,uritemplate,user_agents,whitenoise
 known_first_party = drf_yasg,testproj,articles,people,snippets,todo,users,urlconfs