Deprecated built-in support for OpenAPI schema generation (django-json-api#1253)

Author: sliverc

CHANGELOG.md

@@ -20,6 +20,10 @@ any parts of the framework not mentioned in the documentation should generally b
 
 * Added support for Django 5.1
 
+### Deprecated
+
+* Deprecated built-in support for generating OpenAPI schema. Use [drf-spectacular-json-api](https://github.com/jokiefer/drf-spectacular-json-api/) instead.
+
 ## [7.0.2] - 2024-06-28
 
 ### Fixed

docs/usage.md

@@ -31,7 +31,6 @@ REST_FRAMEWORK = {
         'rest_framework_json_api.renderers.BrowsableAPIRenderer'
     ),
     'DEFAULT_METADATA_CLASS': 'rest_framework_json_api.metadata.JSONAPIMetadata',
-    'DEFAULT_SCHEMA_CLASS': 'rest_framework_json_api.schemas.openapi.AutoSchema',
     'DEFAULT_FILTER_BACKENDS': (
         'rest_framework_json_api.filters.QueryParameterValidationFilter',
         'rest_framework_json_api.filters.OrderingFilter',
@@ -1062,6 +1061,20 @@ DRF has a [OAS schema functionality](https://www.django-rest-framework.org/api-g
 
 DJA extends DRF's schema support to generate an OAS schema in the JSON:API format.
 
+---
+
+**Deprecation notice:**
+
+REST framework's built-in support for generating OpenAPI schemas is
+**deprecated** in favor of 3rd party packages that can provide this
+functionality instead. Therefore we have also deprecated the schema support in
+Django REST framework JSON:API. The built-in support will be retired over the
+next releases.
+
+As a full-fledged replacement, we recommend the [drf-spectacular-json-api] package.
+
+---
+
 ### AutoSchema Settings
 
 In order to produce an OAS schema that properly represents the JSON:API structure
@@ -1187,3 +1200,8 @@ We aim to make creating third party packages as easy as possible, whilst keeping
 To submit new content, [open an issue](https://github.com/django-json-api/django-rest-framework-json-api/issues/new/choose) or [create a pull request](https://github.com/django-json-api/django-rest-framework-json-api/compare).
 
 * [drf-yasg-json-api](https://github.com/glowka/drf-yasg-json-api) - Automated generation of Swagger/OpenAPI 2.0 from Django REST framework JSON:API endpoints.
+* [drf-spectacular-json-api] - OpenAPI 3 schema generator for Django REST framework JSON:API based on drf-spectacular.
+
+
+
+[drf-spectacular-json-api]: https://github.com/jokiefer/drf-spectacular-json-api/

example/tests/test_openapi.py

@@ -1,6 +1,7 @@
 # largely based on DRF's test_openapi
 import json
 
+import pytest
 from django.test import RequestFactory, override_settings
 from django.urls import re_path
 from rest_framework.request import Request
@@ -9,6 +10,8 @@
 
 from example import views
 
+pytestmark = pytest.mark.filterwarnings("ignore:Built-in support")
+
 
 def create_request(path):
     factory = RequestFactory()

rest_framework_json_api/schemas/openapi.py

@@ -423,6 +423,16 @@ def get_operation(self, path, method):
         - collections
         - special handling for POST, PATCH, DELETE
         """
+
+        warnings.warn(
+            DeprecationWarning(
+                "Built-in support for generating OpenAPI schema is deprecated. "
+                "Use drf-spectacular-json-api instead see "
+                "https://github.com/jokiefer/drf-spectacular-json-api/"
+            ),
+            stacklevel=2,
+        )
+
         operation = {}
         operation["operationId"] = self.get_operation_id(path, method)
         operation["description"] = self.get_description(path, method)