Update schema generation doc & add deprecation notice #8453

docs/api-guide/schemas.md

@@ -9,6 +9,23 @@ source:
 >
 > — Heroku, [JSON Schema for the Heroku Platform API][cite]
 
+---
+
+**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. The built-in support will be moved into a separate
+package and then subsequently retired over the next releases.
+
+As a full-fledged replacement, we recommend the [drf-spectacular] package.
+It has extensive support for generating OpenAPI 3 schemas from
+REST framework APIs, with both automatic and customisable options available.
+For further information please refer to
+[Documenting your API](../topics/documenting-your-api.md#drf-spectacular).
+
+---
+
 API schemas are a useful tool that allow for a range of use cases, including
 generating reference documentation, or driving dynamic client libraries that
 can interact with your API.
@@ -438,3 +455,4 @@ create a base `AutoSchema` subclass for your project that takes additional
 [openapi-generator]: https://github.com/OpenAPITools/openapi-generator
 [swagger-codegen]: https://github.com/swagger-api/swagger-codegen
 [info-object]: https://swagger.io/specification/#infoObject
+[drf-spectacular]: https://drf-spectacular.readthedocs.io/en/latest/readme.html

docs/topics/documenting-your-api.md

@@ -4,12 +4,42 @@
 >
 > — Roy Fielding, [REST APIs must be hypertext driven][cite]
 
-REST framework provides built-in support for generating OpenAPI schemas, which
-can be used with tools that allow you to build API documentation.
+REST framework provides a range of different choices for documenting your API. The following
+is a non-exhaustive list of the most popular ones.
 
-There are also a number of great third-party documentation packages available.
+## Third party packages for OpenAPI support
 
-## Generating documentation from OpenAPI schemas
+### drf-spectacular
+
+[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation library with explicit
+focus on extensibility, customizability and client generation. It is the recommended way for
+generating and presenting OpenAPI schemas.
+
+The library aims to extract as much schema information as possible, while providing decorators and extensions for easy
+customization. There is explicit support for [swagger-codegen][swagger], [SwaggerUI][swagger-ui] and [Redoc][redoc],
+i18n, versioning, authentication, polymorphism (dynamic requests and responses), query/path/header parameters,
+documentation and more. Several popular plugins for DRF are supported out-of-the-box as well.
+
+### drf-yasg
+
+[drf-yasg][drf-yasg] is a [Swagger / OpenAPI 2][swagger] generation tool implemented without using the schema generation provided
+by Django Rest Framework.
+
+It aims to implement as much of the [OpenAPI 2][open-api] specification as possible - nested schemas, named models,
+response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code
+generation tools like `swagger-codegen`.
+
+This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`:
+
+![Screenshot - drf-yasg][image-drf-yasg]
+
+---
+
+## Build-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. **
 
 There are a number of packages available that allow you to generate HTML
 documentation pages from OpenAPI schemas.
@@ -124,35 +154,6 @@ urlpatterns = [
 
 See the [ReDoc documentation][redoc] for advanced usage.
 
-## Third party packages
-
-There are a number of mature third-party packages for providing API documentation.
-
-#### drf-yasg - Yet Another Swagger Generator
-
-[drf-yasg][drf-yasg] is a [Swagger][swagger] generation tool implemented without using the schema generation provided
-by Django Rest Framework.
-
-It aims to implement as much of the [OpenAPI][open-api] specification as possible - nested schemas, named models,
-response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code
-generation tools like `swagger-codegen`.
-
-This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`:
-
-
-![Screenshot - drf-yasg][image-drf-yasg]
-
-#### drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework
-
-[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility,
-customizability and client generation. Usage patterns are very similar to [drf-yasg][drf-yasg].
-
-It aims to extract as much schema information as possible, while providing decorators and extensions for easy
-customization. There is explicit support for [swagger-codegen][swagger], [SwaggerUI][swagger-ui] and [Redoc][redoc],
-i18n, versioning, authentication, polymorphism (dynamic requests and responses), query/path/header parameters,
-documentation and more. Several popular plugins for DRF are supported out-of-the-box as well.
-
----
 
 ## Self describing APIs