From b87699c034816123c0ca0371078ccfdf702833c2 Mon Sep 17 00:00:00 2001 From: "T. Franzel" Date: Tue, 22 Nov 2022 14:53:54 +0100 Subject: [PATCH] Update schema generation doc & add deprecation notice #8453 (#8773) * Update schema generation doc & add deprecation notice #8453 * Update docs/topics/documenting-your-api.md Co-authored-by: Tom Christie * Update docs/topics/documenting-your-api.md Co-authored-by: Tom Christie * Update docs/topics/documenting-your-api.md Co-authored-by: Tom Christie Co-authored-by: T. Franzel <13507857+tfranzel@users.noreply.github.com> Co-authored-by: Asif Saif Uddin Co-authored-by: Tom Christie --- docs/api-guide/schemas.md | 18 ++++++++ docs/topics/documenting-your-api.md | 67 +++++++++++++++-------------- 2 files changed, 52 insertions(+), 33 deletions(-) diff --git a/docs/api-guide/schemas.md b/docs/api-guide/schemas.md index e402019a4..3f0b15530 100644 --- a/docs/api-guide/schemas.md +++ b/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 diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 5eabeee7b..b85d6310a 100644 --- a/docs/topics/documenting-your-api.md +++ b/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 an [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] + +--- + +## 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.** 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