Skip to content

Commit eefd5a7

Browse files
committed
adding drf-yasg to the documentation's documenting-your-api section
1 parent 22f1c59 commit eefd5a7

File tree

1 file changed

+17
-0
lines changed

1 file changed

+17
-0
lines changed

docs/topics/documenting-your-api.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,20 @@ The `rest_framework.documentation` module provides three helper functions to hel
136136

137137
There are a number of mature third-party packages for providing API documentation.
138138

139+
---
140+
141+
#### drf-yasg - Yet another Swagger generator
142+
[drf-yasg][drf-yasg] does not rely on the internal DRF's documenting package, the [Core API][core_api].
143+
The rationale was that the Core API has not been able to generate response schemas ([issue #4502][issue_4502]).
144+
145+
This is a major issue when a swagger file is the source for code generation, which is typed (for example when using TypeScript).
146+
147+
The [drf-yasg][drf-yasg] solves this problem.
148+
149+
The other DRF swagger packages listed below are based on the [Core API][core_api]. Consequently, they suffer from the same issue.
150+
151+
---
152+
139153
#### DRF OpenAPI
140154

141155
[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
296310
[image-self-describing-api]: ../img/self-describing.png
297311
[schemas-examples]: ../api-guide/schemas/#example
298312
[metadata-docs]: ../api-guide/metadata/
313+
[drf-yasg]: https://github.com/axnsan12/drf-yasg
314+
[core_api]: http://www.django-rest-framework.org/api-guide/schemas/#core-api
315+
[issue_4502]: https://github.com/encode/django-rest-framework/issues/4502

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy