From d7b20f4244d6bf9ea03f951eb499b9f5ae056f65 Mon Sep 17 00:00:00 2001 From: Rispa Joseph <88330312+RispaJoseph@users.noreply.github.com> Date: Wed, 21 Jan 2026 00:36:45 +0530 Subject: [PATCH 1/3] Fix section title and add note on OpenAPI packages Corrected the hyphenation in the section title and added a note on using third-party packages for OpenAPI support. --- docs/topics/documenting-your-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index edb989290d..4b9d2a906c 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -7,7 +7,9 @@ REST framework provides a range of different choices for documenting your API. The following is a non-exhaustive list of the most popular ones. -## Third party packages for OpenAPI support +## Third-party packages for OpenAPI support + +REST framework recommends using third-party packages for generating and presenting OpenAPI schemas, as they provide more features and flexibility than the built-in (deprecated) implementation. ### drf-spectacular From 5aab82e5eafaa07d6a853ef018852409601174fe Mon Sep 17 00:00:00 2001 From: Rispa Joseph <88330312+RispaJoseph@users.noreply.github.com> Date: Wed, 21 Jan 2026 00:38:38 +0530 Subject: [PATCH 2/3] Refine description of API documentation choices Clarified wording about API documentation options. --- docs/topics/documenting-your-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 4b9d2a906c..58d128469f 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -4,8 +4,7 @@ > > — Roy Fielding, [REST APIs must be hypertext driven][cite] -REST framework provides a range of different choices for documenting your API. The following -is a non-exhaustive list of the most popular ones. +REST framework provides a range of different choices for documenting your API. The following is a non-exhaustive list of some of the most popular options. ## Third-party packages for OpenAPI support From c677adc12e0421f42c3bf0126b1419c800761c16 Mon Sep 17 00:00:00 2001 From: Rispa Joseph <88330312+RispaJoseph@users.noreply.github.com> Date: Fri, 23 Jan 2026 23:12:00 +0530 Subject: [PATCH 3/3] Use warning admonition for OpenAPI deprecation notice Updated deprecation notice for OpenAPI schema generation to clarify the recommendation for using drf-spectacular. --- docs/topics/documenting-your-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 58d128469f..f4fee104bc 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -38,9 +38,9 @@ This also translates into a very useful interactive documentation viewer in the ## Built-in OpenAPI schema generation (deprecated) -**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. -As replacement, we recommend using the [drf-spectacular](#drf-spectacular) package.** +!!! warning + **Deprecation notice:** REST framework's built-in support for generating OpenAPI schemas is deprecated in favor of third-party packages that provide this functionality instead. As a replacement, we recommend using **drf-spectacular**. + There are a number of packages available that allow you to generate HTML documentation pages from OpenAPI schemas.