From 4ceee03893434056d28318fb6bd4ee85f26d57fe Mon Sep 17 00:00:00 2001
From: Oliver Sauder <os@esite.ch>
Date: Thu, 3 Oct 2024 20:42:29 +0400
Subject: [PATCH] Deprecated built-in support for OpenAPI schema generation
 (#1253)

---
 CHANGELOG.md                               |  4 ++++
 docs/usage.md                              | 20 +++++++++++++++++++-
 example/tests/test_openapi.py              |  3 +++
 rest_framework_json_api/schemas/openapi.py | 10 ++++++++++
 4 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae0aaf32..cebd3f8a 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/docs/usage.md b/docs/usage.md
index a50a97f7..1a2cb195 100644
--- a/docs/usage.md
+++ b/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/
diff --git a/example/tests/test_openapi.py b/example/tests/test_openapi.py
index 2333dd6a..fa2f9c73 100644
--- a/example/tests/test_openapi.py
+++ b/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()
diff --git a/rest_framework_json_api/schemas/openapi.py b/rest_framework_json_api/schemas/openapi.py
index b44ce7a4..6892e991 100644
--- a/rest_framework_json_api/schemas/openapi.py
+++ b/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)