Generate components for OpenAPI schemas.

Author: gnuletik

rest_framework/schemas/openapi.py

@@ -1,3 +1,4 @@
+import re
 import warnings
 from collections import OrderedDict
 from decimal import Decimal
@@ -39,16 +40,21 @@ def get_schema(self, request=None, public=False):
         Generate a OpenAPI schema.
         """
         self._initialise_endpoints()
+        components_schemas = {}
 
         # Iterate endpoints generating per method path operations.
-        # TODO: …and reference components.
         paths = {}
         _, view_endpoints = self._get_paths_and_endpoints(None if public else request)
         for path, method, view in view_endpoints:
             if not self.has_view_permissions(path, method, view):
                 continue
 
             operation = view.schema.get_operation(path, method)
+            component = view.schema.get_components(path, method)
+
+            if component is not None:
+                components_schemas.update(component)
+
             # Normalise path for any provided mount url.
             if path.startswith('/'):
                 path = path[1:]
@@ -64,6 +70,11 @@ def get_schema(self, request=None, public=False):
             'paths': paths,
         }
 
+        if len(components_schemas) > 0:
+            schema['components'] = {
+                'schemas': components_schemas
+            }
+
         return schema
 
 # View Inspectors
@@ -101,6 +112,34 @@ def get_operation(self, path, method):
 
         return operation
 
+    def _get_serializer_component_name(self, serializer):
+        if not hasattr(serializer, 'Meta'):
+            return None
+
+        if hasattr(serializer.Meta, 'schema_component_name'):
+            return serializer.Meta.schema_component_name
+
+        # If the serializer has no Meta.schema_component_name, we use
+        # the serializer's class name as the component name.
+        component_name = serializer.__class__.__name__
+        # We remove the "serializer" string from the class name.
+        pattern = re.compile("serializer", re.IGNORECASE)
+        return pattern.sub("", component_name)
+
+    def get_components(self, path, method):
+        serializer = self._get_serializer(path, method)
+
+        if not isinstance(serializer, serializers.Serializer):
+            return None
+
+        component_name = self._get_serializer_component_name(serializer)
+
+        if component_name is None:
+            return None
+
+        content = self._map_serializer(serializer)
+        return {component_name: content}
+
     def _get_operation_id(self, path, method):
         """
         Compute an operation ID from the model, serializer or view name.
@@ -491,6 +530,10 @@ def _get_serializer(self, path, method):
                           .format(view.__class__.__name__, method, path))
             return None
 
+    def _get_reference(self, serializer):
+        component_name = self._get_serializer_component_name(serializer)
+        return {'$ref': '#/components/schemas/{}'.format(component_name)}
+
     def _get_request_body(self, path, method):
         if method not in ('PUT', 'PATCH', 'POST'):
             return {}
@@ -500,20 +543,30 @@ def _get_request_body(self, path, method):
         serializer = self._get_serializer(path, method)
 
         if not isinstance(serializer, serializers.Serializer):
-            return {}
-
-        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]
+            item_schema = {}
+        elif hasattr(serializer, 'Meta'):
+            # If possible, the serializer should use a reference
+            item_schema = self._get_reference(serializer)
+        else:
+            # There is no model, we'll map the serializer's fields
+            item_schema = self._map_serializer(serializer)
+            # No required fields for PATCH
+            if method == 'PATCH':
+                item_schema.pop('required', None)
+            # No read_only fields for request.
+            # 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]
+            for name, schema in item_schema['properties'].copy().items():
+                if 'readOnly' in schema:
+                    del item_schema['properties'][name]
 
         return {
             'content': {
-                ct: {'schema': content}
+                ct: {'schema': item_schema}
                 for ct in self.request_media_types
             }
         }
@@ -529,10 +582,15 @@ 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):
+        if not isinstance(serializer, serializers.Serializer):
+            item_schema = {}
+        elif hasattr(serializer, 'Meta') and hasattr(serializer.Meta, 'model'):
+            # If the serializer uses a model, we should use a reference
+            item_schema = self._get_reference(serializer)
+        else:
+            # There is no model, we'll map the serializer's fields
             item_schema = self._map_serializer(serializer)
             # No write_only fields for response.
             for name, schema in item_schema['properties'].copy().items():

tests/schemas/test_openapi.py

@@ -795,3 +795,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 'ExampleModel' 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)