Merge branch 'master' into labels

Author: JoelLefkowitz

README.rst

@@ -153,7 +153,7 @@ In ``urls.py``:
    )
 
    urlpatterns = [
-      path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
+      path('swagger.<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
       path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
       path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
       ...

src/drf_yasg/app_settings.py

@@ -41,6 +41,7 @@
     'DEFAULT_API_URL': None,
 
     'USE_SESSION_AUTH': True,
+    'USE_COMPAT_RENDERERS': getattr(settings, 'SWAGGER_USE_COMPAT_RENDERERS', True),
     'CSRF_COOKIE_NAME': settings.CSRF_COOKIE_NAME,
     'CSRF_HEADER_NAME': settings.CSRF_HEADER_NAME,
     'SECURITY_DEFINITIONS': {

src/drf_yasg/inspectors/field.py

@@ -6,7 +6,6 @@
 from contextlib import suppress
 from collections import OrderedDict
 from decimal import Decimal
-from inspect import signature as inspect_signature
 
 import typing
 from django.core import validators
@@ -29,6 +28,14 @@
     import pkg_resources
     drf_version = pkg_resources.get_distribution("djangorestframework").version
 
+try:
+    from types import NoneType, UnionType
+
+    UNION_TYPES = (typing.Union, UnionType)
+except ImportError:  # Python < 3.10
+    NoneType = type(None)
+    UNION_TYPES = (typing.Union,)
+
 logger = logging.getLogger(__name__)
 
 
@@ -480,15 +487,6 @@ def decimal_return_type():
     return openapi.TYPE_STRING if rest_framework_settings.COERCE_DECIMAL_TO_STRING else openapi.TYPE_NUMBER
 
 
-def get_origin_type(hint_class):
-    return getattr(hint_class, '__origin__', None) or hint_class
-
-
-def hint_class_issubclass(hint_class, check_class):
-    origin_type = get_origin_type(hint_class)
-    return inspect.isclass(origin_type) and issubclass(origin_type, check_class)
-
-
 hinting_type_info = [
     (bool, (openapi.TYPE_BOOLEAN, None)),
     (int, (openapi.TYPE_INTEGER, None)),
@@ -505,11 +503,15 @@ def hint_class_issubclass(hint_class, check_class):
 if hasattr(typing, 'get_args'):
     # python >=3.8
     typing_get_args = typing.get_args
+    typing_get_origin = typing.get_origin
 else:
     # python <3.8
     def typing_get_args(tp):
         return getattr(tp, '__args__', ())
 
+    def typing_get_origin(tp):
+        return getattr(tp, '__origin__', None)
+
 
 def inspect_collection_hint_class(hint_class):
     args = typing_get_args(hint_class)
@@ -525,12 +527,6 @@ def inspect_collection_hint_class(hint_class):
 hinting_type_info.append(((typing.Sequence, typing.AbstractSet), inspect_collection_hint_class))
 
 
-def _get_union_types(hint_class):
-    origin_type = get_origin_type(hint_class)
-    if origin_type is typing.Union:
-        return hint_class.__args__
-
-
 def get_basic_type_info_from_hint(hint_class):
     """Given a class (eg from a SerializerMethodField's return type hint,
     return its basic type information - ``type``, ``format``, ``pattern``,
@@ -540,21 +536,28 @@ def get_basic_type_info_from_hint(hint_class):
     :return: the extracted attributes as a dictionary, or ``None`` if the field type is not known
     :rtype: OrderedDict
     """
-    union_types = _get_union_types(hint_class)
 
-    if union_types:
+    if typing_get_origin(hint_class) in UNION_TYPES:
         # Optional is implemented as Union[T, None]
-        if len(union_types) == 2 and isinstance(None, union_types[1]):
-            result = get_basic_type_info_from_hint(union_types[0])
+        filtered_types = [t for t in typing_get_args(hint_class) if t is not NoneType]
+        if len(filtered_types) == 1:
+            result = get_basic_type_info_from_hint(filtered_types[0])
             if result:
                 result['x-nullable'] = True
 
             return result
 
         return None
 
+    # resolve the origin class if the class is generic
+    resolved_class = typing_get_origin(hint_class) or hint_class
+
+    # bail out early
+    if not inspect.isclass(resolved_class):
+        return None
+
     for check_class, info in hinting_type_info:
-        if hint_class_issubclass(hint_class, check_class):
+        if issubclass(resolved_class, check_class):
             if callable(info):
                 return info(hint_class)
 
@@ -617,17 +620,19 @@ def field_to_swagger_object(self, field, swagger_object_type, use_references, **
             return self.probe_field_inspectors(serializer, swagger_object_type, use_references, read_only=True)
         else:
             # look for Python 3.5+ style type hinting of the return value
-            hint_class = inspect_signature(method).return_annotation
-
-            if not inspect.isclass(hint_class) and hasattr(hint_class, '__args__'):
-                hint_class = hint_class.__args__[0]
-            if inspect.isclass(hint_class) and not issubclass(hint_class, inspect._empty):
-                type_info = get_basic_type_info_from_hint(hint_class)
-
-                if type_info is not None:
-                    SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type,
-                                                                            use_references, **kwargs)
-                    return SwaggerType(**type_info)
+            hint_class = typing.get_type_hints(method).get('return')
+
+            # annotations such as typing.Optional have an __instancecheck__
+            # hook and will not look like classes, but `issubclass` needs
+            # a class as its first argument, so only in that case abort
+            if inspect.isclass(hint_class) and issubclass(hint_class, inspect._empty):
+                return NotHandled
+
+            type_info = get_basic_type_info_from_hint(hint_class)
+            if type_info is not None:
+                SwaggerType, ChildSwaggerType = self._get_partial_types(field, swagger_object_type,
+                                                                        use_references, **kwargs)
+                return SwaggerType(**type_info)
 
         return NotHandled
 

src/drf_yasg/renderers.py

@@ -46,14 +46,14 @@ class OpenAPIRenderer(_SpecRenderer):
 class SwaggerJSONRenderer(_SpecRenderer):
     """Renders the schema as a JSON document with the generic ``application/json`` mime type."""
     media_type = 'application/json'
-    format = '.json'
+    format = 'json'
     codec_class = OpenAPICodecJson
 
 
 class SwaggerYAMLRenderer(_SpecRenderer):
     """Renders the schema as a YAML document."""
     media_type = 'application/yaml'
-    format = '.yaml'
+    format = 'yaml'
     codec_class = OpenAPICodecYaml
 
 

src/drf_yasg/views.py

@@ -13,7 +13,9 @@
 from .renderers import (
     ReDocOldRenderer,
     ReDocRenderer,
+    SwaggerJSONRenderer,
     SwaggerUIRenderer,
+    SwaggerYAMLRenderer,
     _SpecRenderer,
 )
 
@@ -77,6 +79,20 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal
     validators = validators or []
     _spec_renderers = tuple(renderer.with_validators(validators) for renderer in SPEC_RENDERERS)
 
+    # optionally copy renderers with the validators that are configured above
+    if swagger_settings.USE_COMPAT_RENDERERS:
+        warnings.warn(
+            "SwaggerJSONRenderer & SwaggerYAMLRenderer's `format` has changed to not include a `.` prefix, "
+            "please silence this warning by setting `SWAGGER_USE_COMPAT_RENDERERS = False` "
+            "in your Django settings and ensure your application works "
+            "(check your URLCONF and swagger/redoc URLs).",
+            DeprecationWarning)
+        _spec_renderers += tuple(
+            type(cls.__name__, (cls,), {'format': '.' + cls.format})
+            for cls in _spec_renderers
+            if issubclass(cls, (SwaggerJSONRenderer, SwaggerYAMLRenderer))
+        )
+
     class SchemaView(APIView):
         _ignore_model_permissions = True
         schema = None  # exclude from schema

testproj/testproj/settings/base.py

@@ -151,7 +151,7 @@
 }
 
 REDOC_SETTINGS = {
-    'SPEC_URL': ('schema-json', {'format': '.json'}),
+    'SPEC_URL': ('schema-json', {'format': 'json'}),
 }
 
 # Internationalization

testproj/testproj/urls.py

@@ -54,13 +54,13 @@ def root_redirect(request):
 ]
 
 urlpatterns = [
-    re_path(r'^swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=0),
+    re_path(r'^swagger\.(?P<format>json|yaml)$', SchemaView.without_ui(cache_timeout=0),
             name='schema-json'),
     path('swagger/', SchemaView.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
     path('redoc/', SchemaView.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
     path('redoc-old/', SchemaView.with_ui('redoc-old', cache_timeout=0), name='schema-redoc-old'),
 
-    re_path(r'^cached/swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=None),
+    re_path(r'^cached/swagger\.(?P<format>json|yaml)$', SchemaView.without_ui(cache_timeout=None),
             name='cschema-json'),
     path('cached/swagger/', SchemaView.with_ui('swagger', cache_timeout=None), name='cschema-swagger-ui'),
     path('cached/redoc/', SchemaView.with_ui('redoc', cache_timeout=None), name='cschema-redoc'),

tests/test_get_basic_type_info_from_hint.py

@@ -15,6 +15,19 @@
     ]
 
 
+python310_union_tests = []
+if sys.version_info >= (3, 10):
+    # # New PEP 604 union syntax in Python 3.10+
+    python310_union_tests = [
+        (bool | None, {'type': openapi.TYPE_BOOLEAN, 'format': None, 'x-nullable': True}),
+        (list[int] | None, {
+            'type': openapi.TYPE_ARRAY, 'items': openapi.Items(openapi.TYPE_INTEGER), 'x-nullable': True
+        }),
+        # Following cases are not 100% correct, but it should work somehow and not crash.
+        (int | float, None),
+    ]
+
+
 @pytest.mark.parametrize('hint_class, expected_swagger_type_info', [
     (int, {'type': openapi.TYPE_INTEGER, 'format': None}),
     (str, {'type': openapi.TYPE_STRING, 'format': None}),
@@ -41,7 +54,7 @@
     (type('SomeType', (object,), {}), None),
     (None, None),
     (6, None),
-] + python39_generics_tests)
+] + python39_generics_tests + python310_union_tests)
 def test_get_basic_type_info_from_hint(hint_class, expected_swagger_type_info):
     type_info = get_basic_type_info_from_hint(hint_class)
     assert type_info == expected_swagger_type_info

tests/test_schema_generator.py

@@ -345,7 +345,7 @@ def retrieve(self, request, pk=None):
     )
     swagger = generator.get_schema(None, True)
     property_schema = swagger["definitions"]["OptionalMethod"]["properties"]["x"]
-    assert property_schema == openapi.Schema(title='X', type=expected_type, readOnly=True)
+    assert property_schema == openapi.Schema(title='X', type=expected_type, readOnly=True, x_nullable=True)
 
 
 EXPECTED_DESCRIPTION = """\

tests/test_schema_views.py

@@ -53,6 +53,30 @@ def test_redoc(client, validate_schema):
     _validate_text_schema_view(client, validate_schema, '/redoc/?format=openapi', json.loads)
 
 
+@pytest.mark.urls('urlconfs.legacy_renderer')
+@pytest.mark.parametrize('format', ('.json', '.yaml'))
+def test_swagger_ui_legacy_renderer(settings, client, validate_schema, format):
+    settings.SWAGGER_SETTINGS = {
+        **settings.SWAGGER_SETTINGS,
+        'SPEC_URL': ('schema-json', {'format': format}),
+    }
+
+    _validate_ui_schema_view(client, '/swagger/', 'swagger-ui-dist/swagger-ui-bundle.js')
+    _validate_text_schema_view(client, validate_schema, '/swagger/?format=openapi', json.loads)
+
+
+@pytest.mark.urls('urlconfs.legacy_renderer')
+@pytest.mark.parametrize('format', ('.json', '.yaml'))
+def test_redoc_legacy_renderer(settings, client, validate_schema, format):
+    settings.REDOC_SETTINGS = {
+        **settings.REDOC_SETTINGS,
+        'SPEC_URL': ('schema-json', {'format': format}),
+    }
+
+    _validate_ui_schema_view(client, '/redoc/', 'redoc/redoc.min.js')
+    _validate_text_schema_view(client, validate_schema, '/redoc/?format=openapi', json.loads)
+
+
 def test_caching(client, validate_schema):
     prev_schema = None
 

tests/urlconfs/legacy_renderer.py

@@ -0,0 +1,11 @@
+from django.urls import path, re_path
+
+from testproj.urls import required_urlpatterns, SchemaView
+
+urlpatterns = [
+    re_path(r'^swagger(?P<format>\.json|\.yaml)$', SchemaView.without_ui(cache_timeout=0),
+            name='schema-json'),
+    path('swagger/', SchemaView.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
+    path('redoc/', SchemaView.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
+    path('redoc-old/', SchemaView.with_ui('redoc-old', cache_timeout=0), name='schema-redoc-old'),
+] + required_urlpatterns

tests/urlconfs/ns_versioning.py

@@ -13,7 +13,7 @@ class VersionedSchemaView(SchemaView):
 
 
 schema_patterns = [
-    re_path(r'swagger(?P<format>.json|.yaml)$', VersionedSchemaView.without_ui(), name='ns-schema')
+    re_path(r'swagger\.(?P<format>json|yaml)$', VersionedSchemaView.without_ui(), name='ns-schema')
 ]
 
 

tests/urlconfs/url_versioning.py

@@ -49,6 +49,6 @@ class VersionedSchemaView(SchemaView):
 urlpatterns = required_urlpatterns + [
     re_path(VERSION_PREFIX_URL + r"snippets/$", SnippetList.as_view()),
     re_path(VERSION_PREFIX_URL + r"snippets_excluded/$", ExcludedSnippets.as_view()),
-    re_path(VERSION_PREFIX_URL + r'swagger(?P<format>.json|.yaml)$', VersionedSchemaView.without_ui(),
+    re_path(VERSION_PREFIX_URL + r'swagger\.(?P<format>json|yaml)$', VersionedSchemaView.without_ui(),
             name='vschema-json'),
 ]