diff --git a/docs/img/drfdocs.png b/docs/img/drfdocs.png new file mode 100644 index 000000000..8821c8f13 Binary files /dev/null and b/docs/img/drfdocs.png differ diff --git a/docs/img/rest-framework-docs.png b/docs/img/rest-framework-docs.png deleted file mode 100644 index 736a00955..000000000 Binary files a/docs/img/rest-framework-docs.png and /dev/null differ diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index d65e251f1..8511c8a32 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -12,23 +12,31 @@ The most common way to document Web APIs today is to produce documentation that --- +#### DRF Docs + +[DRF Docs][drfdocs-repo] allows you to Document Web APIs made with Django Rest Framework. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the [website][drfdocs-website] while there is also an available [demo][drfdocs-demo] for people to see what it looks like. + +Features include customizing the template with your branding and settings for hiding the docs depending on the environment. + +![Screenshot - DRF docs][image-drf-docs] + +--- + #### Django REST Swagger 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. -The package is fully documented, well supported, and comes highly recommended. - Django REST Swagger supports REST framework versions 2.3 and above. +Mark is also the author of the [REST Framework Docs][rest-framework-docs] package is which offers clean, simple autogenerated documentation for your API but is depracated and has moved to Django REST Swagger. + + ![Screenshot - Django REST Swagger][image-django-rest-swagger] --- #### REST Framework Docs -The [REST Framework Docs][rest-framework-docs] package is an earlier project, also by Marc Gibbons, that offers clean, simple autogenerated documentation for your API. - -![Screenshot - REST Framework Docs][image-rest-framework-docs] --- @@ -100,13 +108,16 @@ In this approach, rather than documenting the available API endpoints up front, 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. [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs +[drfdocs-website]: http://www.drfdocs.com/ +[drfdocs-demo]: http://demo.drfdocs.com/ [django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger [swagger]: https://developers.helloreverb.com/swagger/ [rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs [apiary]: http://apiary.io/ [markdown]: http://daringfireball.net/projects/markdown/ [hypermedia-docs]: rest-hypermedia-hateoas.md +[image-drf-docs]: ../img/drfdocs.png [image-django-rest-swagger]: ../img/django-rest-swagger.png -[image-rest-framework-docs]: ../img/rest-framework-docs.png [image-apiary]: ../img/apiary.png [image-self-describing-api]: ../img/self-describing.png