Skip to content

Commit 323e1cd

Browse files
jmsmknrpkilby
jmsmkn
authored and
rpkilby
committed
Cleanup "Documenting your API" 3rd party recommendations (#7057)
1 parent 8988afa commit 323e1cd

File tree

4 files changed

+10
-67
lines changed

4 files changed

+10
-67
lines changed

‎docs/community/third-party-packages.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,6 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
254254

255255
* [cookiecutter-django-rest][cookiecutter-django-rest] - A cookiecutter template that takes care of the setup and configuration so you can focus on making your REST apis awesome.
256256
* [djangorestrelationalhyperlink][djangorestrelationalhyperlink] - A hyperlinked serializer that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer.
257-
* [django-rest-swagger][django-rest-swagger] - An API documentation generator for Swagger UI.
258257
* [django-rest-framework-proxy][django-rest-framework-proxy] - Proxy to redirect incoming request to another API server.
259258
* [gaiarestframework][gaiarestframework] - Utils for django-rest-framework
260259
* [drf-extensions][drf-extensions] - A collection of custom extensions
@@ -315,7 +314,6 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
315314
[djangorestframework-rapidjson]: https://github.com/allisson/django-rest-framework-rapidjson
316315
[djangorestframework-chain]: https://github.com/philipn/django-rest-framework-chain
317316
[djangorestrelationalhyperlink]: https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project
318-
[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger
319317
[django-rest-framework-proxy]: https://github.com/eofs/django-rest-framework-proxy
320318
[gaiarestframework]: https://github.com/AppsFuel/gaiarestframework
321319
[drf-extensions]: https://github.com/chibisov/drf-extensions

‎docs/img/apiary.png

-54.3 KB
Binary file not shown.

‎docs/img/django-rest-swagger.png

-75.1 KB
Binary file not shown.

‎docs/topics/documenting-your-api.md

Lines changed: 10 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -140,56 +140,6 @@ This also translates into a very useful interactive documentation viewer in the
140140

141141
---
142142

143-
#### Django REST Swagger
144-
145-
Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints.
146-
147-
Django REST Swagger supports REST framework versions 2.3 and above.
148-
149-
Mark is also the author of the [REST Framework Docs][rest-framework-docs] package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger.
150-
151-
This package is fully documented, well supported, and comes highly recommended.
152-
153-
![Screenshot - Django REST Swagger][image-django-rest-swagger]
154-
155-
---
156-
157-
### DRF AutoDocs
158-
159-
Oleksander Mashianovs' [DRF Auto Docs][drfautodocs-repo] automated api renderer.
160-
161-
Collects almost all the code you written into documentation effortlessly.
162-
163-
Supports:
164-
165-
* functional view docs
166-
* tree-like structure
167-
* Docstrings:
168-
* markdown
169-
* preserve space & newlines
170-
* formatting with nice syntax
171-
* Fields:
172-
* choices rendering
173-
* help_text (to specify SerializerMethodField output, etc)
174-
* smart read_only/required rendering
175-
* Endpoint properties:
176-
* filter_backends
177-
* authentication_classes
178-
* permission_classes
179-
* extra url params(GET params)
180-
181-
![whole structure](http://joxi.ru/52aBGNI4k3oyA0.jpg)
182-
183-
---
184-
185-
#### Apiary
186-
187-
There are various other online tools and services for providing API documentation. One notable service is [Apiary][apiary]. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing & prototyping, and various other tools.
188-
189-
![Screenshot - Apiary][image-apiary]
190-
191-
---
192-
193143
## Self describing APIs
194144

195145
The browsable API that REST framework provides makes it possible for your API to be entirely self describing. The documentation for each API endpoint can be provided simply by visiting the URL in your browser.
@@ -253,22 +203,17 @@ In this approach, rather than documenting the available API endpoints up front,
253203
To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documentation includes pointers to background reading, as well as links to various hypermedia formats.
254204

255205
[cite]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
256-
[drf-yasg]: https://github.com/axnsan12/drf-yasg/
257-
[image-drf-yasg]: ../img/drf-yasg.png
258-
[drfautodocs-repo]: https://github.com/iMakedonsky/drf-autodocs
259-
[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger
260-
[swagger]: https://swagger.io/
261-
[open-api]: https://openapis.org/
262-
[rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs
263-
[apiary]: https://apiary.io/
264-
[markdown]: https://daringfireball.net/projects/markdown/syntax
206+
265207
[hypermedia-docs]: rest-hypermedia-hateoas.md
266-
[image-django-rest-swagger]: ../img/django-rest-swagger.png
267-
[image-apiary]: ../img/apiary.png
268-
[image-self-describing-api]: ../img/self-describing.png
269208
[metadata-docs]: ../api-guide/metadata/
270-
271209
[schemas-examples]: ../api-guide/schemas/#examples
272-
[swagger-ui]: https://swagger.io/tools/swagger-ui/
273-
[redoc]: https://github.com/Rebilly/ReDoc
274210

211+
[image-drf-yasg]: ../img/drf-yasg.png
212+
[image-self-describing-api]: ../img/self-describing.png
213+
214+
[drf-yasg]: https://github.com/axnsan12/drf-yasg/
215+
[markdown]: https://daringfireball.net/projects/markdown/syntax
216+
[open-api]: https://openapis.org/
217+
[redoc]: https://github.com/Rebilly/ReDoc
218+
[swagger]: https://swagger.io/
219+
[swagger-ui]: https://swagger.io/tools/swagger-ui/

0 commit comments

Comments
 (0)