Add schema references for OpenAPI generation, see #6984

Author: gnuletik

rest_framework/schemas/openapi.py

@@ -1,4 +1,5 @@
 import warnings
+from enum import Enum
 from operator import attrgetter
 from urllib.parse import urljoin
 
@@ -39,12 +40,18 @@ def get_paths(self, request=None):
 
         # Only generate the path prefix for paths that will be included
         if not paths:
-            return None
+            return None, None
+
+        components_schemas = {}
 
         for path, method, view in view_endpoints:
             if not self.has_view_permissions(path, method, view):
                 continue
-            operation = view.schema.get_operation(path, method)
+            operation, operation_schema = view.schema.get_operation(path, method)
+
+            if operation_schema is not None:
+                components_schemas.update(operation_schema)
+
             # Normalise path for any provided mount url.
             if path.startswith('/'):
                 path = path[1:]
@@ -53,24 +60,29 @@ def get_paths(self, request=None):
             result.setdefault(path, {})
             result[path][method.lower()] = operation
 
-        return result
+        return result, components_schemas
 
     def get_schema(self, request=None, public=False):
         """
         Generate a OpenAPI schema.
         """
         self._initialise_endpoints()
 
-        paths = self.get_paths(None if public else request)
+        paths, components_schemas = self.get_paths(None if public else request)
         if not paths:
             return None
 
         schema = {
             'openapi': '3.0.2',
             'info': self.get_info(),
-            'paths': paths,
+            'paths': paths
         }
 
+        if len(components_schemas) > 0:
+            schema['components'] = {
+                'schemas': components_schemas
+            }
+
         return schema
 
 # View Inspectors
@@ -106,7 +118,9 @@ def get_operation(self, path, method):
             operation['requestBody'] = request_body
         operation['responses'] = self._get_responses(path, method)
 
-        return operation
+        component_schema = self._get_component_schema(path, method)
+
+        return operation, component_schema
 
     def _get_operation_id(self, path, method):
         """
@@ -479,29 +493,67 @@ def _get_serializer(self, method, path):
                           .format(view.__class__.__name__, method, path))
             return None
 
-    def _get_request_body(self, path, method):
-        if method not in ('PUT', 'PATCH', 'POST'):
+    class SchemaMode(Enum):
+        RESPONSE = 1
+        BODY = 2
+
+    def _get_item_schema(self, serializer, schema_mode, method):
+        if not isinstance(serializer, serializers.Serializer):
             return {}
 
-        self.request_media_types = self.map_parsers(path, method)
+        # If the serializer uses a model, we should use a reference
+        if hasattr(serializer, 'Meta') and hasattr(serializer.Meta, 'model'):
+            model_name = serializer.Meta.model.__name__
+            return {'$ref': '#/components/schemas/{}'.format(model_name)}
+
+        # There is no model, we'll map the serializer's fields
+        item_schema = self._map_serializer(serializer)
 
+        if schema_mode == self.SchemaMode.RESPONSE:
+            # No write_only fields for response.
+            for name, schema in item_schema['properties'].copy().items():
+                if 'writeOnly' in schema:
+                    del item_schema['properties'][name]
+                    if 'required' in item_schema:
+                        item_schema['required'] = [f for f in item_schema['required'] if f != name]
+
+        elif schema_mode == self.SchemaMode.BODY:
+            # No required fields for PATCH
+            if method == 'PATCH':
+                item_schema.pop('required', None)
+            # No read_only fields for request.
+            for name, schema in item_schema['properties'].copy().items():
+                if 'readOnly' in schema:
+                    del item_schema['properties'][name]
+
+        return item_schema
+
+    def _get_component_schema(self, path, method):
         serializer = self._get_serializer(path, method)
 
         if not isinstance(serializer, serializers.Serializer):
-            return {}
+            return None
+
+        # If the model has no model, then the serializer will be inlined
+        if not hasattr(serializer, 'Meta') or not hasattr(serializer.Meta, 'model'):
+            return None
 
+        model_name = serializer.Meta.model.__name__
         content = self._map_serializer(serializer)
-        # No required fields for PATCH
-        if method == 'PATCH':
-            content.pop('required', None)
-        # No read_only fields for request.
-        for name, schema in content['properties'].copy().items():
-            if 'readOnly' in schema:
-                del content['properties'][name]
+
+        return {model_name: content}
+
+    def _get_request_body(self, path, method):
+        if method not in ('PUT', 'PATCH', 'POST'):
+            return {}
+
+        self.request_media_types = self.map_parsers(path, method)
+
+        serializer = self._get_serializer(path, method)
 
         return {
             'content': {
-                ct: {'schema': content}
+                ct: {'schema': self._get_item_schema(serializer, self.SchemaMode.BODY, method)}
                 for ct in self.request_media_types
             }
         }
@@ -517,17 +569,8 @@ def _get_responses(self, path, method):
 
         self.response_media_types = self.map_renderers(path, method)
 
-        item_schema = {}
         serializer = self._get_serializer(path, method)
-
-        if isinstance(serializer, serializers.Serializer):
-            item_schema = self._map_serializer(serializer)
-            # No write_only fields for response.
-            for name, schema in item_schema['properties'].copy().items():
-                if 'writeOnly' in schema:
-                    del item_schema['properties'][name]
-                    if 'required' in item_schema:
-                        item_schema['required'] = [f for f in item_schema['required'] if f != name]
+        item_schema = self._get_item_schema(serializer, self.SchemaMode.RESPONSE, method)
 
         if is_list_view(path, method, self.view):
             response_schema = {

tests/schemas/test_openapi.py

@@ -84,7 +84,7 @@ def test_path_without_parameters(self):
         inspector = AutoSchema()
         inspector.view = view
 
-        operation = inspector.get_operation(path, method)
+        operation, _ = inspector.get_operation(path, method)
         assert operation == {
             'operationId': 'listDocStringExamples',
             'description': 'A description of my GET operation.',
@@ -116,7 +116,7 @@ def test_path_with_id_parameter(self):
         inspector = AutoSchema()
         inspector.view = view
 
-        operation = inspector.get_operation(path, method)
+        operation, _ = inspector.get_operation(path, method)
         assert operation == {
             'operationId': 'RetrieveDocStringExampleDetail',
             'description': 'A description of my GET operation.',
@@ -659,7 +659,7 @@ def test_paths_construction(self):
         generator = SchemaGenerator(patterns=patterns)
         generator._initialise_endpoints()
 
-        paths = generator.get_paths()
+        paths, _ = generator.get_paths()
 
         assert '/example/' in paths
         example_operations = paths['/example/']
@@ -676,7 +676,7 @@ def test_prefixed_paths_construction(self):
         generator = SchemaGenerator(patterns=patterns)
         generator._initialise_endpoints()
 
-        paths = generator.get_paths()
+        paths, _ = generator.get_paths()
 
         assert '/v1/example/' in paths
         assert '/v1/example/{id}/' in paths
@@ -689,7 +689,7 @@ def test_mount_url_prefixed_to_paths(self):
         generator = SchemaGenerator(patterns=patterns, url='/api')
         generator._initialise_endpoints()
 
-        paths = generator.get_paths()
+        paths, _ = generator.get_paths()
 
         assert '/api/example/' in paths
         assert '/api/example/{id}/' in paths
@@ -733,3 +733,18 @@ def test_schema_information_empty(self):
 
         assert schema['info']['title'] == ''
         assert schema['info']['version'] == ''
+
+    def test_serializer_model(self):
+        """Construction of the top level dictionary."""
+        patterns = [
+            url(r'^example/?$', views.ExampleGenericAPIViewModel.as_view()),
+        ]
+        generator = SchemaGenerator(patterns=patterns)
+
+        request = create_request('/')
+        schema = generator.get_schema(request=request)
+
+        print(schema)
+        assert 'components' in schema
+        assert 'schemas' in schema['components']
+        assert 'OpenAPIExample' in schema['components']['schemas']

tests/schemas/views.py

@@ -4,6 +4,7 @@
     DecimalValidator, MaxLengthValidator, MaxValueValidator,
     MinLengthValidator, MinValueValidator, RegexValidator
 )
+from django.db import models
 
 from rest_framework import generics, permissions, serializers
 from rest_framework.decorators import action
@@ -137,3 +138,29 @@ def get(self, *args, **kwargs):
                                          url='http://localhost', uuid=uuid.uuid4(), ip4='127.0.0.1', ip6='::1',
                                          ip='192.168.1.1')
         return Response(serializer.data)
+
+
+# Serializer with model.
+class OpenAPIExample(models.Model):
+    first_name = models.CharField(max_length=30)
+
+
+class ExampleSerializerModel(serializers.Serializer):
+    date = serializers.DateField()
+    datetime = serializers.DateTimeField()
+    hstore = serializers.HStoreField()
+    uuid_field = serializers.UUIDField(default=uuid.uuid4)
+
+    class Meta:
+        model = OpenAPIExample
+
+
+class ExampleGenericAPIViewModel(generics.GenericAPIView):
+    serializer_class = ExampleSerializerModel
+
+    def get(self, *args, **kwargs):
+        from datetime import datetime
+        now = datetime.now()
+
+        serializer = self.get_serializer(data=now.date(), datetime=now)
+        return Response(serializer.data)