From af1beb85290a70605dd9cb99ee95d619b5f4c3ec Mon Sep 17 00:00:00 2001 From: Oliver Sauder Date: Thu, 3 Oct 2024 09:34:59 +0400 Subject: [PATCH 1/2] Deprecated built-in support for OpenAPI schema generation --- 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..ef27d2b7 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', @@ -1057,6 +1056,20 @@ The `prefetch_related` case will issue 4 queries, but they will be small and fas ## Generating an OpenAPI Specification (OAS) 3.0 schema document +--- + +**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. + +--- + DRF has a [OAS schema functionality](https://www.django-rest-framework.org/api-guide/schemas/) to generate an [OAS 3.0 schema](https://www.openapis.org/) as a YAML or JSON file. @@ -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) From 77be7435f20ec130107c6666db05599f2eec0827 Mon Sep 17 00:00:00 2001 From: Oliver Sauder Date: Thu, 3 Oct 2024 19:19:32 +0400 Subject: [PATCH 2/2] Adjusted so deprecation notice which is a block comes after text --- docs/usage.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index ef27d2b7..1a2cb195 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1056,6 +1056,11 @@ The `prefetch_related` case will issue 4 queries, but they will be small and fas ## Generating an OpenAPI Specification (OAS) 3.0 schema document +DRF has a [OAS schema functionality](https://www.django-rest-framework.org/api-guide/schemas/) to generate an +[OAS 3.0 schema](https://www.openapis.org/) as a YAML or JSON file. + +DJA extends DRF's schema support to generate an OAS schema in the JSON:API format. + --- **Deprecation notice:** @@ -1070,11 +1075,6 @@ As a full-fledged replacement, we recommend the [drf-spectacular-json-api] packa --- -DRF has a [OAS schema functionality](https://www.django-rest-framework.org/api-guide/schemas/) to generate an -[OAS 3.0 schema](https://www.openapis.org/) as a YAML or JSON file. - -DJA extends DRF's schema support to generate an OAS schema in the JSON:API format. - ### AutoSchema Settings In order to produce an OAS schema that properly represents the JSON:API structure pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy