Documenting APIs is an important part of building modern software, most times, the engineer building the API is different from the one using the API, therefore the API should be easy to be understood and easily used by the engineer consuming it without having to always ask the one creating it on how to interact with the API.
My favorite is Coreapi, my colleagues at work prefer Swagger but somehow a few others and I love coreapi, so I try to provide 2-3 documentation formats.
"Using a Core API client is a more robust and meaningful way to interact with your API than constructing HTTP requests and decoding responses. The dynamic client library is always up to date with the API, and client code focuses solely on the interface being provided, rather that dealing with network details and encodings."
Coreapi also allows you to interact with API directly from your browser. I also love the feature that lets you switch the programming language sample request/response will .
One of the most popular packages/libs for documenting Django APIs is called Swagger. Swagger is a wonderful tool that provides information on the internals of an API, it also comes with a feature that allows the user to interact with the endpoints directly from the browser, without writing any code.
Installing both tools is simple and straightforward.
pip install swagger
Add to settings.py
INSTALLED_APPS = [ # ... 'rest_framework', 'rest_framework_swagger', ]
Add path to the swagger docs
from rest_framework_swagger.views import get_swagger_view schema_view = get_swagger_view(title='Deals API') # ... urlpatterns = [ # ... path(r'docs/', schema_view), ]
Congratulations on installing Swagger!
pip install coreapi
include coreapi urls
from rest_framework.documentation import include_docs_urls # ... urlpatterns = [ # ... path(r'docs/', include_docs_urls(title='Deals API')), ]
boom! you have coreapi working as shown below
There are many customizations that can be done on both libs and when I tried using both on Django 2.3 and python3.6, both libs failed to work together on same project.
Hopefully I will keep updating this as I learn new stuff.