django-drf-boilerplate API Docs

Currently, some projects are using Apiary, others a self-hosted solution and others don't have an API documentation.

First: is it worth writing API docs to all projects? Does it take too much time?

I think it's worth, even if it requires some time to be written. This way the frontend/mobile devs don't have to ask the backend dev for info on how to use the API all the time and the backend devs have a good overview when starting on a new project.

Second: what is the best solution? Apiary is simple and has a beautiful UI, but it's expensive for team support (USD99/month). A self-hosted solution requires some work to be implemented (but it can be done only once and added to the boilerplate).

@jonatasbaldin is already working on self-hosted API docs for SU's API, it's using API Blueprint specification and being compiled as an HTML file by aglio, which is served by a simple Django view. Maybe it could be our solution here, if we go that way.

Feb 20 '17 17:02 smaniotto

Hey @smaniotto,

I think an API documentation is needed for any project, as it has a lot of benefits (my next blog post will talk about it). It totally pays off on the long run.

About the SU, our API documentation is a view rendering a HTML page. This HTML page is generated by aglio during our build from a file on the backend repository.

Here's what I found good about that:

The solution os open source (Django, Aglio and Blueprint)
We don't pay s***
We can control the API documentation access with Django's permissions
The actual API code (Blueprint file) is stored in the backend repository, it's versioned

The cons:

Aglio uses node (hahah kidding JS guys), but we do need to have Python and Node on the server
Aglio last update was three months ago and there's a lot of open PRs and issues, they are maybe waiting for a new release of Blueprint or not. So we may need to change the render. Apiary has a client too, which we could give it a shot.

I think this is the way to go, now. Apiary is expensive and the UI kinda sux. Using Python/node on the same server isn't that bad, but we could find (or build) a renderer in Python that works nicely with Django.

Anyone has other opinion about that?