Merge pull request #20 from axnsan12/release/1.0.5

Version 1.0.5

.codecov.yml

@@ -11,14 +11,15 @@ coverage:
       default:
         enabled: yes
         target: auto
+        threshold: 0%
         if_no_uploads: error
         if_ci_failed: error
 
     patch:
       default:
         enabled: yes
         target: 80%
-        threshold: 60%
+        threshold: 0%
         if_no_uploads: error
         if_ci_failed: error
 

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.sh text eol=lf

.travis.yml

@@ -40,3 +40,8 @@ after_success:
 branches:
   only:
     - master
+
+notifications:
+  email:
+    on_success: always
+    on_failure: always

README.rst

@@ -359,7 +359,7 @@ https://drf-yasg.readthedocs.io/en/latest/
    :alt: Codecov
 
 .. |pypi-version| image:: https://img.shields.io/pypi/v/drf-yasg.svg
-   :target: https://pypi.org/project/drf-yasg/
+   :target: https://pypi.python.org/pypi/drf-yasg/
    :alt: PyPI
 
 .. |rtd-badge| image:: https://img.shields.io/readthedocs/drf-yasg.svg

docs/changelog.rst

@@ -3,20 +3,31 @@ Changelog
 #########
 
 
+*********
+**1.0.5**
+*********
+
+- **FIXED:** fixed a crash caused by having read-only Serializers nested by reference
+- **FIXED:** removed erroneous backslashes in paths when routes are generated using Django 2
+  `path() <https://docs.djangoproject.com/en/2.0/ref/urls/#django.urls.path>`_
+- **IMPROVED:** updated ``swagger-ui`` to version 3.7.0
+- **IMPROVED:** ``FileField`` is now generated as an URL or file name in response Schemas
+  (:pr:`21`, thanks to :ghuser:`h-hirokawa`)
+
 *********
 **1.0.4**
 *********
 
-- **FIX:** fixed improper generation of YAML references
-- **FEATURE:** added ``query_serializer`` parameter to
+- **FIXED:** fixed improper generation of YAML references
+- **ADDED:** added ``query_serializer`` parameter to
   :func:`@swagger_auto_schema <.swagger_auto_schema>` (:issue:`16`, :pr:`17`)
 
 *********
 **1.0.3**
 *********
 
-- **FIX:** fixed bug that caused schema views returned from cache to fail (:issue:`14`)
-- **FIX:** disabled automatic generation of response schemas for form operations to avoid confusing errors caused by
+- **FIXED:** fixed bug that caused schema views returned from cache to fail (:issue:`14`)
+- **FIXED:** disabled automatic generation of response schemas for form operations to avoid confusing errors caused by
   attempting to shove file parameters into Schema objects
 
 *********

docs/conf.py

@@ -4,6 +4,7 @@
 # drf-yasg documentation build configuration file, created by
 # sphinx-quickstart on Sun Dec 10 15:20:34 2017.
 import os
+import re
 import sys
 
 import sphinx_rtd_theme
@@ -168,6 +169,7 @@
 
     ('py:class', 'ruamel.yaml.dumper.SafeDumper'),
     ('py:class', 'rest_framework.renderers.BaseRenderer'),
+    ('py:class', 'rest_framework.schemas.generators.EndpointEnumerator'),
     ('py:class', 'rest_framework.views.APIView'),
 
     ('py:class', 'OpenAPICodecYaml'),
@@ -215,40 +217,59 @@
 
 # custom interpreted role for linking to GitHub issues and pull requests
 # use as :issue:`14` or :pr:`17`
-gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/%d"
-gh_pr_uri = "https://github.com/axnsan12/drf-yasg/pull/%d"
+gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/{}"
+gh_pr_uri = "https://github.com/axnsan12/drf-yasg/pull/{}"
+gh_user_uri = "https://github.com/{}"
+
+
+def sphinx_err(inliner, lineno, rawtext, msg):
+    msg = inliner.reporter.error(msg, line=lineno)
+    prb = inliner.problematic(rawtext, rawtext, msg)
+    return [prb], [msg]
+
+
+def sphinx_ref(options, rawtext, text, ref):
+    set_classes(options)
+    node = nodes.reference(rawtext, text, refuri=ref, **options)
+    return [node], []
+
+
+def role_github_user(name, rawtext, text, lineno, inliner, options=None, content=None):
+    options = options or {}
+    content = content or []
+
+    if not re.match(r"^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$", text):
+        return sphinx_err(inliner, lineno, rawtext, '"%s" is not a valid GitHub username.' % text)
+
+    ref = gh_user_uri.format(text)
+    text = '@' + utils.unescape(text)
+    return sphinx_ref(options, rawtext, text, ref)
 
 
 def role_github_pull_request_or_issue(name, rawtext, text, lineno, inliner, options=None, content=None):
     options = options or {}
     content = content or []
     try:
-        ghid = int(text)
-        if ghid <= 0:
+        if int(text) <= 0:
             raise ValueError
     except ValueError:
-        msg = inliner.reporter.error(
-            'GitHub pull request or issue number must be a number greater than or equal to 1; '
-            '"%s" is invalid.' % text, line=lineno
+        return sphinx_err(
+            inliner, lineno, rawtext,
+            'GitHub pull request or issue number must be a number greater than or equal to 1; "%s" is invalid.' % text
         )
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-        # Base URL mainly used by inliner.rfc_reference, so this is correct:
 
     if name == 'pr':
         ref = gh_pr_uri
     elif name == 'issue':
         ref = gh_issue_uri
     else:
-        msg = inliner.reporter.error('unknown tag name for GitHub reference - "%s"' % name, line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
+        return sphinx_err(inliner, lineno, rawtext, 'unknown role name for GitHub reference - "%s"' % name)
 
-    ref = ref % ghid
-    set_classes(options)
-    node = nodes.reference(rawtext, '#' + utils.unescape(text), refuri=ref, **options)
-    return [node], []
+    ref = ref.format(text)
+    text = '#' + utils.unescape(text)
+    return sphinx_ref(options, rawtext, text, ref)
 
 
 roles.register_local_role('pr', role_github_pull_request_or_issue)
 roles.register_local_role('issue', role_github_pull_request_or_issue)
+roles.register_local_role('ghuser', role_github_user)

docs/custom_spec.rst

@@ -158,7 +158,9 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
       test_param = openapi.Parameter('test', openapi.IN_QUERY, description="test manual param", type=openapi.TYPE_BOOLEAN)
       user_response = openapi.Response('response description', UserSerializer)
 
+      # 'method' can be used to customize a single HTTP method of a view
       @swagger_auto_schema(method='get', manual_parameters=[test_param], responses={200: user_response})
+      # 'methods' can be used to apply the same modification to multiple methods
       @swagger_auto_schema(methods=['put', 'post'], request_body=UserSerializer)
       @api_view(['GET', 'PUT', 'POST'])
       def user_detail(request, pk):
@@ -187,6 +189,7 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
    .. code:: python
 
       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'])
          def today(self, request):
@@ -206,6 +209,45 @@ Where you can use the :func:`@swagger_auto_schema <.swagger_auto_schema>` decora
          def partial_update(self, request, *args, **kwargs):
             ...
 
+.. Tip::
+
+   If you want to customize the generation of a method you are not implementing yourself, you can use
+   ``swagger_auto_schema`` in combination with Django's ``method_decorator``:
+
+   .. code:: python
+
+      @method_decorator(name='list', decorator=swagger_auto_schema(
+          operation_description="description from swagger_auto_schema via method_decorator"
+      ))
+      class ArticleViewSet(viewsets.ModelViewSet):
+         ...
+
+   This allows you to avoid unnecessarily overriding the method.
+
+.. Tip::
+
+   You can go even further and directly decorate the result of ``as_view``, in the same manner you would
+   override an ``@api_view`` as described above:
+
+   .. code:: python
+
+      decorated_login_view = \
+         swagger_auto_schema(
+            method='post',
+            responses={status.HTTP_200_OK: LoginResponseSerializer}
+         )(LoginView.as_view())
+
+      urlpatterns = [
+         ...
+         url(r'^login/$', decorated_login_view, name='login')
+      ]
+
+   This can allow you to avoid skipping an unnecessary *subclass* altogether.
+
+.. Warning::
+
+   However, do note that both of the methods above can lead to unexpected (and maybe surprising) results by
+   replacing/decorating methods on the base class itself.
 
 *************************
 Subclassing and extending