Biking Endorphines - REST-API Documentation

What can you use for API documentation?

According to topic Documenting your API at Django-Rest-Framework you have following options to use as API documentation:

1. Django REST Framework documentation

This is the most basic documentation that you can get "out of the box" - almost.
The only dependency needed here is the "renderer" - to be more precise - the `coreapi`.

2. DRF Docs

Quoting information Django-REST-Framework Documentation topic:

DRF Docs allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis.
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 while there is also a demo available for people to see what it looks like.
Live API Endpoints allow you to utilize the endpoints from within the documentation in a neat way.

3. Django REST Swagger

Quoting information Django-REST-Framework Documentation topic:

Marc Gibbons' Django REST Swagger integrates REST framework with the Swagger API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints.
Django REST Swagger supports REST framework versions 2.3 and above.
Mark is also the author of the REST Framework Docs package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger.
Both this package and DRF docs are fully documented, well supported, and come highly recommended.

4. DRF AutoDocs

Quoting information Django-REST-Framework Documentation topic:

Oleksander Mashianovs' DRF Auto Docs automated api renderer.
Collects almost all the code you written into documentation effortlessly.
Supports:

- functional view docs
- tree-like structure
- Docstrings:
- markdown
- preserve space & newlines
- formatting with nice syntax
- Fields:
- choices rendering
- help_text (to specify SerializerMethodField output, etc)
- smart read_only/required rendering
- Endpoint properties:
- filter_backends
- authentication_classes
- permission_classes
- extra url params(GET params)

Why we chose DRF for documentation of Biking-Endorphines

Other options ( DRF Docs and Django REST Swagger) uses swagger-ui for documentation. In my professional career I've already used swagger-ui.

I'd probably do some follow-up about how to use other options, but this time I want to use something out-of-box.

How do we implement documentation of our project??

Just like in other's options, first you need to document your API! So let's check how it will look like, shall we?

class UserList(generics.ListCreateAPIView):
    """
    get:
    Return a list of all existing users.

    post:
    Create a new user instance.
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer

Now that we finally add documentation (it was just few comment-code on class ), we can add dependencies to our django application:

(At urls.py):

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^api/user/$', views.UserList.as_view()),
    url(r'^docs/', include_docs_urls(title='API Documentation')), # TEST
]

Also for API to be accessible and handled you need to install coreapi that's used as default for rendering.

pip install coreapi
pip install coreapi-cli

Final result

I've figure out best solution to deliver code that is not yet merged into master is by using Annotated tagging.

So to get source-code you can wget'it or check it at this tag-release information

Code commits done for this post:

Tools and applications used:

LL (Lessons Learned)

1. Heroku - how things failed.

I had too-ambitious plan of deploying source-code to Heroku to have a working example od Documentation out-of-the-box.

Unfortunatelly last time I've used Heroku was in January 2016, so I didn't remember a lot about it.

Also proper setup of project was needed from beginning, moving on with tutorial step-by-step.

As our project is not best compatible with heroku setup, I've found myself in situation where there is more work needed to properly deploy content.

Everything would work, but unfortunatelly the static pages setup was not good enought for documentation, which you can check here

Solution:

Follow tutorial about How to use Heroku in Django-Based projects. For those impatient, you can use template for Django 1.10 that is supported with Heroku

I will make a follow-up article about how to properly setup your project using Heroku, and also how to fix your project if have different directory structure (as BikingEndorphines has).

Tips & Tricks

1. Too Many Ancestors! Pylint Error.

So After using documentation and trying the generic-class based Django REST Framework I've found myself having this issue.

Initialy I've made a workaround using # pylint disable=too-many-ancestors, but then I've figure out - It's ugly, it should be setup in pylintrc!

And so the hunt for setup in pylintrc began, finally checking this article at StackOverFlow I've found resolution - by changing one variable at pylintrc - max-parents=15 which will conclude in using more then 7 default class inheritance.

Acknowledgements

Accomplished:

1. Making API documentation - research for best API documentation!

What's next

1. How to secure biking-endorphines REST-API.

2. Badge Gathering source-code and tests.

Comments

comments powered by Disqus