Merge branch 'feature/yaml-docs' of github.com:pySilver/django-rest-swagger into feature/yaml

Conflicts:
	README.md
	rest_framework_swagger/__init__.py
	rest_framework_swagger/static/rest_framework_swagger/index.html
	rest_framework_swagger/static/rest_framework_swagger/lib/jquery.cookie.js
	rest_framework_swagger/templates/rest_framework_swagger/index.html
	rest_framework_swagger/urlparser.py
	setup.py

Author: Marc Gibbons

README.md

@@ -121,7 +121,10 @@ Many thanks to Tom Christie & all the contributors who have developed [Django RE
 * Darren Thompson (@WhiteDawn)
 * Lukasz Balcerzak (@lukaszb)
 * David Newgas (@davidn)
+<<<<<<< HEAD
 * Bozidar Benko (@bbenko)
+=======
+>>>>>>> b9401b6cb4d500600df632d6819fea5389eea402
 
 
 ### Django REST Framework Docs contributors:

cigar_example/cigar_example/settings.py

@@ -1,4 +1,5 @@
 # Django settings for cigar_example project.
+from os.path import dirname, abspath, join
 
 DEBUG = True
 TEMPLATE_DEBUG = DEBUG
@@ -8,10 +9,13 @@
 
 MANAGERS = ADMINS
 
+DJANGO_ROOT = dirname(dirname(abspath(__file__)))
+root = lambda *x: abspath(join(abspath(DJANGO_ROOT), *x))
+
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.sqlite3',  # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'.
-        'NAME': 'db.sql',  # Or path to database file if using sqlite3.
+        'NAME': root('db.sql'),  # Or path to database file if using sqlite3.
         'USER': '',  # Not used with sqlite3.
         'PASSWORD': '',  # Not used with sqlite3.
         'HOST': '',  # Set to empty string for localhost. Not used with sqlite3.

cigar_example/requirements.txt

@@ -1,7 +1,7 @@
 Django==1.5.5
 PyYAML==3.10
 argh==0.23.2
-argparse==1.2.1
+argparse==1.1
 coverage==3.6
 distribute==0.6.49
 django-nose==1.2

rest_framework_swagger/docgenerator.py

@@ -2,16 +2,26 @@
 from django.http import HttpRequest
 
 from rest_framework import viewsets
+from rest_framework.serializers import BaseSerializer
 
 from .introspectors import APIViewIntrospector, \
     ViewSetIntrospector, BaseMethodIntrospector, IntrospectorHelper, \
-    get_resolved_value
+    get_resolved_value, YAMLDocstringParser
 
 
 class DocumentationGenerator(object):
+    # Serializers defined in docstrings
+    explicit_serializers = set()
+
+    # Serializers defined in fields
+    fields_serializers = set()
+
+    # Response classes defined in docstrings
+    explicit_response_types = dict()
+
     def generate(self, apis):
         """
-        Returns documentaion for a list of APIs
+        Returns documentation for a list of APIs
         """
         api_docs = []
         for api in apis:
@@ -43,21 +53,37 @@ def get_operations(self, api):
                     method_introspector.get_http_method() == "OPTIONS":
                 continue  # No one cares. I impose JSON.
 
-            serializer = method_introspector.get_serializer_class()
-            serializer_name = IntrospectorHelper.get_serializer_name(serializer)
+            doc_parser = YAMLDocstringParser(
+                docstring=method_introspector.get_docs())
+
+            serializer = self._get_method_serializer(
+                doc_parser, method_introspector)
+
+            response_type = self._get_method_response_type(
+                doc_parser, serializer, introspector, method_introspector)
 
             operation = {
-                'httpMethod': method_introspector.get_http_method(),
+                'method': method_introspector.get_http_method(),
                 'summary': method_introspector.get_summary(),
                 'nickname': method_introspector.get_nickname(),
                 'notes': method_introspector.get_notes(),
-                'responseClass': serializer_name,
+                'type': response_type,
             }
 
-            parameters = method_introspector.get_parameters()
-            if len(parameters) > 0:
+            if doc_parser.yaml_error is not None:
+                operation['notes'] += "<pre>YAMLError:\n {err}</pre>".format(
+                    err=doc_parser.yaml_error)
+
+            response_messages = doc_parser.get_response_messages()
+            parameters = doc_parser.discover_parameters(
+                inspector=method_introspector)
+
+            if parameters:
                 operation['parameters'] = parameters
 
+            if response_messages:
+                operation['responseMessages'] = response_messages
+
             operations.append(operation)
 
         return operations
@@ -68,19 +94,120 @@ def get_models(self, apis):
         DRF serializers and their fields
         """
         serializers = self._get_serializer_set(apis)
+        serializers.update(self.explicit_serializers)
+        serializers.update(
+            self._find_field_serializers(serializers)
+        )
 
         models = {}
 
         for serializer in serializers:
-            properties = self._get_serializer_fields(serializer)
+            data = self._get_serializer_fields(serializer)
 
-            models[serializer.__name__] = {
-                'id': serializer.__name__,
-                'properties': properties,
+            # Register 2 models with different subset of properties suitable
+            # for data reading and writing.
+            # i.e. rest framework does not output write_only fields in response
+            # or require read_only fields in complex input.
+
+            serializer_name = IntrospectorHelper.get_serializer_name(serializer)
+            # Writing
+            # no readonly fields
+            w_name = "Write{serializer}".format(serializer=serializer_name)
+
+            w_properties = dict((k, v) for k, v in data['fields'].items()
+                                if k not in data['read_only'])
+
+            models[w_name] = {
+                'id': w_name,
+                'required': [i for i in data['required'] if i in w_properties.keys()],
+                'properties': w_properties,
             }
 
+            # Reading
+            # no write_only fields
+            r_name = serializer_name
+
+            r_properties = dict((k, v) for k, v in data['fields'].items()
+                                if k not in data['write_only'])
+
+            models[r_name] = {
+                'id': r_name,
+                'required': [i for i in r_properties.keys()],
+                'properties': r_properties,
+            }
+
+            # Enable original model for testing purposes
+            # models[serializer_name] = {
+            #     'id': serializer_name,
+            #     'required': data['required'],
+            #     'properties': data['fields'],
+            # }
+
+        models.update(self.explicit_response_types)
+        models.update(self.fields_serializers)
         return models
 
+    def _get_method_serializer(self, doc_parser, method_inspector):
+        """
+        Returns serializer used in method.
+        Registers custom serializer from docstring in scope.
+
+        Serializer might be ignored if explicitly told in docstring
+        """
+        serializer = method_inspector.get_serializer_class()
+
+        docstring_serializer = doc_parser.get_serializer_class(
+            callback=method_inspector.callback
+        )
+
+        if doc_parser.get_response_type() is not None:
+            # Custom response class detected
+            return None
+
+        if docstring_serializer is not None:
+            self.explicit_serializers.add(docstring_serializer)
+            serializer = docstring_serializer
+
+        if doc_parser.should_omit_serializer():
+            serializer = None
+
+        return serializer
+
+    def _get_method_response_type(self, doc_parser, serializer,
+                                  view_inspector, method_inspector):
+        """
+        Returns response type for method.
+        This might be custom `type` from docstring or discovered
+        serializer class name.
+
+        Once custom `type` found in docstring - it'd be
+        registered in a scope
+        """
+        response_type = doc_parser.get_response_type()
+        if response_type is not None:
+            # Register class in scope
+            view_name = view_inspector.callback.__name__
+            view_name = view_name.replace('ViewSet', '')
+            view_name = view_name.replace('APIView', '')
+            view_name = view_name.replace('View', '')
+            response_type_name = "{view}{method}Response".format(
+                view=view_name,
+                method=method_inspector.method.title().replace('_', '')
+            )
+            self.explicit_response_types.update({
+                response_type_name: {
+                    "id": response_type_name,
+                    "properties": response_type
+                }
+            })
+            return response_type_name
+        else:
+            serializer_name = IntrospectorHelper.get_serializer_name(serializer)
+            if serializer_name is not None:
+                return serializer_name
+
+            return None
+
     def _get_serializer_set(self, apis):
         """
         Returns a set of serializer classes for a provided list
@@ -95,30 +222,95 @@ def _get_serializer_set(self, apis):
 
         return serializers
 
+    def _find_field_serializers(self, serializers):
+        """
+        Returns set of serializers discovered from fields
+        """
+        serializers_set = set()
+        for serializer in serializers:
+            fields = serializer().get_fields()
+            for name, field in fields.items():
+                if isinstance(field, BaseSerializer):
+                    serializers_set.add(field)
+
+        return serializers_set
+
     def _get_serializer_fields(self, serializer):
         """
         Returns serializer fields in the Swagger MODEL format
         """
         if serializer is None:
             return
 
-        fields = serializer().get_fields()
+        if hasattr(serializer, '__call__'):
+            fields = serializer().get_fields()
+        else:
+            fields = serializer.get_fields()
 
-        data = {}
+        data = {
+            'fields': {},
+            'required': [],
+            'write_only': [],
+            'read_only': [],
+        }
         for name, field in fields.items():
+            if getattr(field, 'write_only', False):
+                data['write_only'].append(name)
 
-            data[name] = {
-                'type': field.type_label,
-                'required': getattr(field, 'required', None),
-                'allowableValues': {
-                    'min': getattr(field, 'min_length', None),
-                    'max': getattr(field, 'max_length', None),
-                    'defaultValue': get_resolved_value(field, 'default', None),
-                    'readOnly': getattr(field, 'read_only', None),
-                    'valueType': 'RANGE',
-                }
+            if getattr(field, 'read_only', False):
+                data['read_only'].append(name)
+
+            if getattr(field, 'required', False):
+                data['required'].append(name)
+
+            data_type = field.type_label
+
+            # guess format
+            data_format = 'string'
+            if data_type in BaseMethodIntrospector.PRIMITIVES:
+                data_format = BaseMethodIntrospector.PRIMITIVES.get(data_type)[0]
+
+            f = {
+                'description': getattr(field, 'help_text', ''),
+                'type': data_type,
+                'format': data_format,
+                'required': getattr(field, 'required', False),
+                'defaultValue': get_resolved_value(field, 'default'),
+                'readOnly': getattr(field, 'read_only', None),
             }
 
+            # Min/Max values
+            max_val = getattr(field, 'max_val', None)
+            min_val = getattr(field, 'min_val', None)
+            if max_val is not None and data_type == 'integer':
+                f['minimum'] = min_val
+
+            if max_val is not None and data_type == 'integer':
+                f['maximum'] = max_val
+
+            # ENUM options
+            if field.type_label == 'multiple choice' \
+                    and isinstance(field.choices, list):
+                f['enum'] = [k for k, v in field.choices]
+
+            # Support for complex types
+            if isinstance(field, BaseSerializer):
+                field_serializer = IntrospectorHelper.get_serializer_name(field)
+
+                if getattr(field, 'write_only', False):
+                    field_serializer = "Write{}".format(field_serializer)
+
+                f['type'] = field_serializer
+                if field.many:
+                    f['type'] = 'array'
+                    if data_type in BaseMethodIntrospector.PRIMITIVES:
+                        f['items'] = {'type': data_type}
+                    else:
+                        f['items'] = {'$ref': field_serializer}
+
+            # memorize discovered field
+            data['fields'][name] = f
+
         return data
 
     def _get_serializer_class(self, callback):