Skip to content

Commit

Permalink
Deprecated built-in support for OpenAPI schema generation (#1253)
Browse files Browse the repository at this point in the history
  • Loading branch information
sliverc authored Oct 3, 2024
1 parent 5123a26 commit 4ceee03
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 1 deletion.
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 19 additions & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/
3 changes: 3 additions & 0 deletions example/tests/test_openapi.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -9,6 +10,8 @@

from example import views

pytestmark = pytest.mark.filterwarnings("ignore:Built-in support")


def create_request(path):
factory = RequestFactory()
Expand Down
10 changes: 10 additions & 0 deletions rest_framework_json_api/schemas/openapi.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down

0 comments on commit 4ceee03

Please sign in to comment.