move OAS schema initialization from AutoSchema to SchemaGenerator

Author: n2ygk

docs/usage.md

@@ -1,4 +1,3 @@
-`
 # Usage
 
 The DJA package implements a custom renderer, parser, exception handler, query filter backends, and
@@ -978,41 +977,43 @@ REST_FRAMEWORK = {
 }
 ```
 
-### View-based
+### Add some static OAS schema content
 
-You can explicitly use DJA's AutoSchema in your view definition, optionally including an OAS schema document
-initializer:
+You can optionally include an OAS schema document initialization by subclassing SchemaGenerator
+and setting `schema_init`.
 
-```python
-from rest_framework_json_api.schemas.openapi import AutoSchema
-
-TODO: resolve this with upstream changes:
+Here's an example that fills out OAS `info` and `servers` objects.
 
-openapi_schema = {
-    'info': {
-        'version': '1.0',
-        'title': 'my demo API',
-        'description': 'A demonstration of [OAS 3.0](https://www.openapis.org) AutoSchema',
-        'contact': {
-            'name': 'my name'
-        },
-        'license': {
-            'name': 'BSD 2 clause',
-            'url': 'https://github.com/django-json-api/django-rest-framework-json-api/blob/master/LICENSE',
-        }
-    },
-    'servers': [
-        {'url': 'https://localhost/v1', 'description': 'local docker'},
-        {'url': 'http://localhost:8000/v1', 'description': 'local dev'},
-        {'url': 'https://api.example.com/v1', 'description': 'demo server'},
-        {'url': '{serverURL}', 'description': 'provide your server URL',
-         'variables': {'serverURL': {'default': 'http://localhost:8000/v1'}}}
-    ]
-}
+```python
+from rest_framework_json_api.schemas.openapi import SchemaGenerator as JSONAPISchemaGenerator
 
 
-class MyViewSet(ModelViewSet):
-    schema = AutoSchema(openapi_schema=openapi_schema)
+class SchemaGenerator(JSONAPISchemaGenerator):
+    """
+    Describe my OAS schema info in detail and list the servers where it can be found
+    """
+    #: fill in some of the openapi schema
+	schema_init = {
+		'info': {
+			'version': '1.0',
+			'title': 'my demo API',
+			'description': 'A demonstration of [OAS 3.0](https://www.openapis.org)',
+			'contact': {
+				'name': 'my name'
+			},
+			'license': {
+				'name': 'BSD 2 clause',
+				'url': 'https://github.com/django-json-api/django-rest-framework-json-api/blob/master/LICENSE',
+			}
+		},
+		'servers': [
+			{'url': 'https://localhost/v1', 'description': 'local docker'},
+			{'url': 'http://localhost:8000/v1', 'description': 'local dev'},
+			{'url': 'https://api.example.com/v1', 'description': 'demo server'},
+			{'url': '{serverURL}', 'description': 'provide your server URL',
+			 'variables': {'serverURL': {'default': 'http://localhost:8000/v1'}}}
+        ]
+    }
 ```
 
 ### Get Schema in View
@@ -1025,20 +1026,16 @@ from rest_framework_json_api.schemas.openapi import SchemaGenerator
 ...
 
 urlpatterns = [
-    path('openapi', get_schema_view(
-        title="Example API",
-        description="API for all things …",
-        version="1.0.0",
-        generator_class=SchemaGenerator
-    ), name='openapi-schema'),
+    path('openapi', get_schema_view(generator_class='myapp.views.SchemaGenerator'), name='openapi-schema'),
     ...
 ]
 ```
 ### Get Schema on Command Line
 To generate an OAS schema document, use something like:
 
 ```text
-$ django-admin generateschema --settings=example.settings >myschema.yaml
+$ django-admin generateschema --settings=example.settings \
+                              --generator_class myapp.views.SchemaGenerator >myschema.yaml
 ```
 
 You can then use any number of OAS tools such as

rest_framework_json_api/schemas/openapi.py

@@ -1,4 +1,5 @@
 import warnings
+from deepmerge import always_merger
 from urllib.parse import urljoin
 
 from django.db.models.fields import related_descriptors as rd
@@ -12,7 +13,7 @@
 from rest_framework_json_api import serializers
 from rest_framework_json_api.views import RelationshipView
 
-#: static OAS 3.0 component definitions that are referenced by AutoSchema.
+#: static OAS 3.0 component definitions that are referenced by SchemaGenerator.
 JSONAPI_COMPONENTS = {
     'schemas': {
         'jsonapi': {
@@ -270,11 +271,18 @@ class SchemaGenerator(drf_openapi.SchemaGenerator):
     """
     Extend DRF's SchemaGenerator to implement jsonapi-flavored generateschema command
     """
+    #: JSONAPI component defintions that are referenced by the generated OAS schema.
+    jsonapi_components = JSONAPI_COMPONENTS
+    #: optional added OAS schema initialization. Make a subclass and override as needed.
+    schema_init = {}
+
     def __init__(self, *args, **kwargs):
-        self.openapi_schema = {}
         super().__init__(*args, **kwargs)
         if not hasattr(self, 'check_duplicate_operation_id'):
             self.check_duplicate_operation_id = lambda paths: None
+        # static JSONAPI fields that get $ref'd to in the view mappings
+        # merge in our reference data on top of anything provided by the init.
+        self.schema_init = always_merger.merge(self.schema_init, {'components': self.jsonapi_components})
 
     def get_schema(self, request=None, public=False):
         """
@@ -283,7 +291,6 @@ def get_schema(self, request=None, public=False):
         """
         self._initialise_endpoints()
         components_schemas = {}
-        components_schemas.update(JSONAPI_COMPONENTS)
 
         # Iterate endpoints generating per method path operations.
         paths = {}
@@ -334,9 +341,6 @@ def get_schema(self, request=None, public=False):
 
             paths.setdefault(path, {})
             paths[path][method.lower()] = operation
-            if hasattr(view.schema, 'openapi_schema'):  # TODO: still needed?
-                # TODO: shallow or deep merge?
-                self.openapi_schema = {**self.openapi_schema, **view.schema.openapi_schema}
 
         self.check_duplicate_operation_id(paths)
 
@@ -345,10 +349,11 @@ def get_schema(self, request=None, public=False):
             'openapi': '3.0.2',
             'info': self.get_info(),
             'paths': paths,
-            'components': components_schemas,
+            'components': {
+                'schemas': components_schemas,
+            }
         }
-
-        return schema
+        return always_merger.merge(schema, self.schema_init)
 
     def _expand_relationships(self, path, method, view):
         """
@@ -437,23 +442,12 @@ class AutoSchema(drf_openapi.AutoSchema):
     """
     content_types = ['application/vnd.api+json']
 
-    def __init__(self, openapi_schema=None, **kwargs):
+    def __init__(self, **kwargs):
         """
         Initialize the JSONAPI OAS schema generator
         :param openapi_schema: dict: OAS 3.0 document with initial values.
         """
         super().__init__(**kwargs)
-        #: allow initialization of OAS schema doc TODO: still needed?
-        if openapi_schema is None:
-            openapi_schema = {}
-        self.openapi_schema = openapi_schema
-        # static JSONAPI fields that get $ref'd to in the view mappings
-        jsonapi_ref = {
-            'components': JSONAPI_COMPONENTS
-        }
-        # merge in our reference data on top of anything provided by the init.
-        # TODO: shallow or deep merge?
-        self.openapi_schema = {**self.openapi_schema, **jsonapi_ref}
 
         # DRF >= 3.12 (not yet released) has changed a bunch of private methods to public.
         # Accommodate those renamings for DRF < 3.12

setup.py

@@ -96,7 +96,7 @@ def get_package_data(package):
     extras_require={
         'django-polymorphic': ['django-polymorphic>=2.0'],
         'django-filter': ['django-filter>=2.0'],
-        'openapi': ['pyyaml>=5.3', 'uritemplate>=3.0.1']
+        'openapi': ['pyyaml>=5.3', 'uritemplate>=3.0.1', 'deepmerge>=0.1.0',]
     },
     setup_requires=wheel,
     python_requires=">=3.5",