encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-08-03 12:00:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

adding drf-yasg to the documentation's documenting-your-api section

Browse Source
This commit is contained in:
Jiri Puc 2018-01-01 19:59:25 +01:00
parent 22f1c59099
commit eefd5a7f9f
1 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -136,6 +136,20 @@ The `rest_framework.documentation` module provides three helper functions to hel
There are a number of mature third-party packages for providing API documentation. There are a number of mature third-party packages for providing API documentation.
---
#### drf-yasg - Yet another Swagger generator
[drf-yasg][drf-yasg] does not rely on the internal DRF's documenting package, the [Core API][core_api].
The rationale was that the Core API has not been able to generate response schemas ([issue #4502][issue_4502]).
This is a major issue when a swagger file is the source for code generation, which is typed (for example when using TypeScript).
The [drf-yasg][drf-yasg] solves this problem.
The other DRF swagger packages listed below are based on the [Core API][core_api]. Consequently, they suffer from the same issue.
---
#### DRF OpenAPI #### DRF OpenAPI
[DRF OpenAPI][drf-openapi] bridges the gap between OpenAPI specification and tool chain with the schema exposed [DRF OpenAPI][drf-openapi] bridges the gap between OpenAPI specification and tool chain with the schema exposed
@ -296,3 +310,6 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
[image-self-describing-api]: ../img/self-describing.png [image-self-describing-api]: ../img/self-describing.png
[schemas-examples]: ../api-guide/schemas/#example [schemas-examples]: ../api-guide/schemas/#example
[metadata-docs]: ../api-guide/metadata/ [metadata-docs]: ../api-guide/metadata/
[drf-yasg]: https://github.com/axnsan12/drf-yasg
[core_api]: http://www.django-rest-framework.org/api-guide/schemas/#core-api
[issue_4502]: https://github.com/encode/django-rest-framework/issues/4502