initial implementation of OAS 3.0 generateschema

Author: n2ygk

CHANGELOG.md

@@ -16,6 +16,7 @@ This release is not backwards compatible. For easy migration best upgrade first
 ### Added
 
 * Add support for Django REST framework 3.10.
+* Add support for `generateschema` management command.
 
 ### Removed
 

docs/usage.md

@@ -1,4 +1,4 @@
-
+`
 # Usage
 
 The DJA package implements a custom renderer, parser, exception handler, query filter backends, and
@@ -876,3 +876,48 @@ The `prefetch_related` case will issue 4 queries, but they will be small and fas
 ### Relationships
 ### Errors
 -->
+
+## Generating an OpenAPI Specification (OAS) 3.0 schema document
+
+DRF 3.10 added a new management command: `generateschema` which can generate an
+[OAS 3.0 schema](https://www.openapis.org/) as a YAML or JSON file.
+
+In order to produce an OAS schema that properly represents the JSON:API structure,
+DJA has this same command as an override of DRF's. In order to make sure the DJA
+version of the command is used, you must add DJA **ahead of** DRF in the
+`INSTALLED_APPS` settings as in this example:
+```python
+INSTALLED_APPS = [
+    'django.contrib.contenttypes',
+    'django.contrib.staticfiles',
+    'django.contrib.sites',
+    'django.contrib.sessions',
+    'django.contrib.auth',
+    'rest_framework_json_api',
+    'rest_framework',
+    'polymorphic',
+    'example',
+    'debug_toolbar',
+    'django_filters',
+]
+```
+
+To generate an OAS schema document, use something like:
+
+```text
+$ django-admin generateschema --settings=example.settings >myschema.yaml
+```
+
+You can then use any number of OAS tools such as
+[swagger-ui-watcher](https://www.npmjs.com/package/swagger-ui-watcher)
+to render the schema:
+```text
+$ swagger-ui-watcher myschema.yaml
+```
+
+Note: Swagger-ui-watcher will complain that "DELETE operations cannot have a requestBody"
+but it will still work. This 
+[error](https://github.com/OAI/OpenAPI-Specification/pull/1937)
+in the OAS specification is expected to be fixed soon.
+([swagger-ui](https://www.npmjs.com/package/swagger-ui) will work silently.)
+

example/settings/dev.py

@@ -1,5 +1,9 @@
 import os
 
+from rest_framework import VERSION as DRFVERSION
+
+drf_version = tuple(int(x) for x in DRFVERSION.split('.'))
+
 SITE_ID = 1
 DEBUG = True
 
@@ -21,6 +25,7 @@
     'django.contrib.sites',
     'django.contrib.sessions',
     'django.contrib.auth',
+    'rest_framework_json_api',
     'rest_framework',
     'polymorphic',
     'example',
@@ -99,3 +104,6 @@
     ),
     'TEST_REQUEST_DEFAULT_FORMAT': 'vnd.api+json'
 }
+
+if drf_version >= (3, 10):
+    REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS'] = 'rest_framework_json_api.schemas.openapi.AutoSchema'