Merge branch 'develop'

Author: marcgibbons

CHANGELOG.md

@@ -89,5 +89,5 @@ Many thanks to Tom Christie & all the contributors who have developed [Django RE
 [pypi]: https://pypi.python.org/pypi/django-rest-swagger
 [license-badge]: https://img.shields.io/pypi/l/django-rest-swagger.svg
 [license]: https://pypi.python.org/pypi/django-rest-swagger/
-[docs-badge]: https://readthedocs.org/projects/django-rest-swagger/badge/
-[docs]: http://django-rest-swagger.readthedocs.org/
+[docs-badge]: https://readthedocs.io/projects/django-rest-swagger/badge/
+[docs]: http://django-rest-swagger.readthedocs.io/

README.md

@@ -6,7 +6,7 @@ Markdown
 django-rest-swagger will parse docstrings as markdown if `Markdown <https://pypi.python.org/pypi/Markdown>`_ is installed.
 
 reStructuredText
------------------
+----------------
 django-rest-swagger can be configured to parse docstrings as reStructuredText.
 
 Add to your settings:
@@ -18,7 +18,7 @@ Add to your settings:
     }
 
 Swagger 'nickname' attribute
------------------
+----------------------------
 By default, django-rest-swagger uses django-rest-framework's get_view_name to resolve the `nickname` attribute
 of a Swagger operation. You can specify an alternative function for `nickname` resolution using the following setting:
 
@@ -36,4 +36,18 @@ This function should use the following signature:
 
 -:code:`cls` The view class providing the operation.
 
--:code:`suffix` The string name of the class method which is providing the operation.
+-:code:`suffix` The string name of the class method which is providing the operation.
+
+
+Swagger 'list' views
+--------------------
+
+django-rest-swagger introspects your views and viewset methods in order to determine the serializer used.
+
+In the majority of cases, the object returned is a single type. However, there are times where multiple serialized
+objects can be returned, such as in the case of `list` methods.
+
+When you use ViewSets, django-rest-swagger will report that the `list` method on a viewset returns a list of objects.
+
+For other ViewSet methods or function based views, you can also hint to django-rest-swagger that the view response is
+also a list, rather than a single object. See :ref:`many`

docs/source/misc.rst

@@ -12,6 +12,7 @@ Example:
         'exclude_namespaces': [],
         'api_version': '0.1',
         'api_path': '/',
+        'relative_paths': False,
         'enabled_methods': [
             'get',
             'post',
@@ -154,6 +155,13 @@ Then in app/views.py:
         from django.http import HttpResponse
         return HttpResponse('you have no permissions!')
 
+relative_paths
+--------------
+
+set to True to make API paths relative to specified :code:`api_path`.
+
+Default: :code:`False`
+
 resource_access_handler
 -------------------------
 

docs/source/settings.rst

@@ -30,6 +30,7 @@ Example:
 
         serializer: .serializers.FooSerializer
         omit_serializer: false
+        many: true
 
         parameters_strategy: merge
         omit_parameters:
@@ -97,7 +98,7 @@ to populate :code:`type` you can specify it with :code:`pytype`:
     pytype: .serializers.FooSerializer
 
 Overriding parameters
---------------------
+---------------------
 
 parameters_strategy
 ~~~~~~~~~~~~~~~~~~~
@@ -176,6 +177,23 @@ signature as follows:
         required: false
         type: url
 
+.. _many:
+
+many
+----
+
+In cases where an API response is a list of objects, it is possible to mark
+this to django-rest-swagger by overriding :code:`many` to `True`.
+
+.. code-block:: yaml
+
+    many: true
+
+This overrides the :code:`type` returned to be an array of the resolved API
+type. ViewSet :code:`list` methods do not require this definition, and are
+marked as :code:`many` automatically.
+
+
 responseMessages 
 ---------------------------------
 To document error codes that your APIView might throw

docs/source/yaml.rst

@@ -1,11 +1,12 @@
-VERSION = '0.3.5'
+VERSION = '0.3.7'
 
 DEFAULT_SWAGGER_SETTINGS = {
     'exclude_url_names': [],
     'exclude_namespaces': [],
     'api_version': '',
     'api_path': '/',
     'api_key': '',
+    'relative_paths': False,
     'token_type': 'Token',
     'enabled_methods': ['get', 'post', 'put', 'patch', 'delete'],
     'is_authenticated': False,

rest_framework_swagger/__init__.py

@@ -119,6 +119,14 @@ def get_operations(self, api, apis=None):
             if produces:
                 operation['produces'] = produces
 
+            # Check if this method has been reported as returning an
+            # array response
+            if method_introspector.is_array_response:
+                operation['items'] = {
+                    '$ref': operation['type']
+                }
+                operation['type'] = 'array'
+
             operations.append(operation)
 
         return operations

rest_framework_swagger/docgenerator.py

@@ -181,6 +181,11 @@ def __init__(self, view_introspector, method):
         self.path = view_introspector.path
         self.user = view_introspector.user
 
+    @property
+    def is_array_response(self):
+        """ Support definition of array responses with the 'many' attr """
+        return self.get_yaml_parser().object.get('many')
+
     def get_module(self):
         return self.callback.__module__
 
@@ -669,6 +674,12 @@ def __init__(self, view_introspector, method, http_method):
             .__init__(view_introspector, method)
         self.http_method = http_method.upper()
 
+    @property
+    def is_array_response(self):
+        """ ViewSet.list methods always return array responses """
+        return (self.method == 'list' or
+                super(ViewSetMethodIntrospector, self).is_array_response)
+
     def get_http_method(self):
         return self.http_method
 

rest_framework_swagger/introspectors.py

@@ -694,7 +694,7 @@ var SwaggerOperation = function(nickname, path, method, parameters, summary, not
 
     // for 1.1 compatibility
     var type = param.type || param.dataType;
-    if(type === 'array') {
+    if(type === 'array' && 'items' in param) {
       type = 'array[' + (param.items.$ref ? param.items.$ref : param.items.type) + ']';
     }
     param.type = type;

rest_framework_swagger/static/rest_framework_swagger/lib/swagger.js

@@ -4,24 +4,34 @@
 
 from django.conf import settings
 from django.utils import six
+from django.utils.six.moves.urllib_parse import urljoin
 from django.core.urlresolvers import RegexURLResolver, RegexURLPattern
 from django.contrib.admindocs.views import simplify_regex
 
 from rest_framework.views import APIView
 
 from .apidocview import APIDocView
+from . import SWAGGER_SETTINGS
 
 
 class UrlParser(object):
 
-    def get_apis(self, patterns=None, urlconf=None, filter_path=None, exclude_url_names=[], exclude_namespaces=[]):
+    __relative_path_matcher__ = re.compile(
+        r'^%s(?P<relative>.*)' % SWAGGER_SETTINGS.get('api_path', ''))
+
+    def get_apis(self, patterns=None, urlconf=None, filter_path=None,
+                 exclude_url_names=None, exclude_namespaces=None):
         """
         Returns all the DRF APIViews found in the project URLs
 
         patterns -- supply list of patterns (optional)
         exclude_url_names -- list of url names to ignore (optional)
         exclude_namespaces -- list of namespaces to ignore (optional)
         """
+        exclude_url_names = exclude_url_names or []
+        exclude_namespaces = exclude_namespaces or []
+        filter_path = self.__make_absolute__(filter_path)
+
         if patterns is None and urlconf is not None:
             if isinstance(urlconf, six.string_types):
                 urls = import_module(urlconf)
@@ -39,6 +49,7 @@ def get_apis(self, patterns=None, urlconf=None, filter_path=None, exclude_url_na
             exclude_namespaces=exclude_namespaces,
         )
         if filter_path is not None:
+            filter_path = self.__make_relative__(filter_path, strip=True)
             return self.get_filtered_apis(apis, filter_path)
 
         return apis
@@ -115,6 +126,7 @@ def __assemble_endpoint_data__(self, pattern, prefix='', filter_path=None):
                 return None
 
         path = path.replace('<', '{').replace('>', '}')
+        path = self.__make_relative__(path)
 
         if self.__exclude_format_endpoints__(path):
             return
@@ -125,18 +137,22 @@ def __assemble_endpoint_data__(self, pattern, prefix='', filter_path=None):
             'callback': callback,
         }
 
-    def __flatten_patterns_tree__(self, patterns, prefix='', filter_path=None, exclude_url_names=[], exclude_namespaces=[]):
+    def __flatten_patterns_tree__(self, patterns, prefix='', filter_path=None,
+                                  exclude_url_names=None, exclude_namespaces=None):
         """
         Uses recursion to flatten url tree.
 
         patterns -- urlpatterns list
         prefix -- (optional) Prefix for URL pattern
         """
+        exclude_url_names = exclude_url_names or []
+        exclude_namespaces = exclude_namespaces or []
         pattern_list = []
 
         for pattern in patterns:
             if isinstance(pattern, RegexURLPattern):
-                endpoint_data = self.__assemble_endpoint_data__(pattern, prefix, filter_path=filter_path)
+                endpoint_data = self.__assemble_endpoint_data__(
+                    pattern, prefix, filter_path=filter_path)
 
                 if endpoint_data is None or pattern.name in exclude_url_names:
                     continue
@@ -145,7 +161,8 @@ def __flatten_patterns_tree__(self, patterns, prefix='', filter_path=None, exclu
 
             elif isinstance(pattern, RegexURLResolver):
 
-                if pattern.namespace is not None and pattern.namespace in exclude_namespaces:
+                if pattern.namespace is not None \
+                        and pattern.namespace in exclude_namespaces:
                     continue
 
                 pref = prefix + pattern.regex.pattern
@@ -196,3 +213,24 @@ def __exclude_format_endpoints__(self, path):
             return True
 
         return False
+
+    def __make_relative__(self, path, strip=False):
+        """
+        When `relative_paths` is True, make path relative to API Path.
+        """
+        if path:
+            if SWAGGER_SETTINGS.get('relative_paths', False):
+                res = UrlParser.__relative_path_matcher__.match(path)
+                path = urljoin('/', res.groups()[0]) if res else path
+
+            return path.strip('/') if strip else path
+
+    def __make_absolute__(self, path):
+        """
+        When `relative_paths` is True, fully qualify path with API Path.
+        """
+        if path:
+            if SWAGGER_SETTINGS.get('relative_paths', False):
+                path = urljoin(SWAGGER_SETTINGS.get('api_path'), path)
+
+            return path