encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-11-22 01:26:53 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update schema generation doc & add deprecation notice #8453 (#8773)

Browse Source 
* Update schema generation doc & add deprecation notice #8453

* Update docs/topics/documenting-your-api.md

Co-authored-by: Tom Christie <tom@tomchristie.com>

* Update docs/topics/documenting-your-api.md

Co-authored-by: Tom Christie <tom@tomchristie.com>

* Update docs/topics/documenting-your-api.md

Co-authored-by: Tom Christie <tom@tomchristie.com>

Co-authored-by: T. Franzel <13507857+tfranzel@users.noreply.github.com>
Co-authored-by: Asif Saif Uddin <auvipy@gmail.com>
Co-authored-by: Tom Christie <tom@tomchristie.com>
This commit is contained in:
T. Franzel 2022-11-22 14:53:54 +01:00 committed by GitHub
parent fd7d3a7b92
commit b87699c034
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 52 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/api-guide/schemas.md
View File

@ -9,6 +9,23 @@ source:
>
> &mdash; 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

67
docs/topics/documenting-your-api.md
View File

@ -4,12 +4,42 @@
>
> &mdash; 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