mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-25 11:04:02 +03:00
* 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:
parent
fd7d3a7b92
commit
b87699c034
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in New Issue
Block a user