API Docs

[oliverroick]

We should start documenting our API as we implement it.

Some documentation frameworks we could use:

• DRF docs
• Swagger
• Docbox

[linzjax]

Depends on what the ultimate goal is.

If we want documentation that has live endpoints and minimal effort to maintain: drf docs seems like the best bet (despite some oddness getting it to cooperate with versioning).

If we want really nice drawn out documentation with explanations and examples side by side: docbox. There are several examples of how slick this can look.

Swagger seems to fall somewhere in between: not as easy to set up as drf docs, and not as explanatory as docbox could be (and not in markdown, which docbox is). There's one specifically for drf, but after fighting with it for a little while gave up on it.

[ian-ross]

Can we add textual explanations to DRF Docs? Can it be made to pick up docstrings from the views or anything like that?

My personal preference would be to go for a quick and simple solution for now so that we have at least some API documentation. We can then revisit later to make it fancy when we have something worth being fancy about!

[linzjax]

Looks like yes, it can pick up docstrings. I still need to figure out why it's stripping out /v1/, but aside from that simple works for me.

[ian-ross]

See what @oliverroick says, but as far as I'm concerned, if it can process docstrings and it looks half-way decent, that's good enough for now!

[oliverroick]

I like the look of DRF docs, but what I'm missing is example responses for the API endpoints. We might be able to add these examples to the docstrings, but that will clutter up our sources with comments. However, from quickly looking at the documentation, there wasn't any information that it picks up docstrings at all.

Docbox provides way more flexibility for what we want to describe in our docs. I might seem like its more work because we have to write everything ourselves, but it's probably the way to go if we want to create useful documentation. On the other hand, we already create the API design documents in markdown, we could use those as a start.

[ian-ross]

@oliverroick I guess it depends on what our initial goals for the API docs are. Do we want to just get something done quickly while we're developing, then revisit for "proper" documentation later? Or do we want to do "proper" documentation as we go along right from the start? If it's the first, we should probably use DRF Docs, since it requires next to no effort. If it's the second, we should use something that allows us more control over the output documentation (so probably Docbox).

I don't mind which we do: I think it's going to be some time before we have people outside Cadasta making serious use of the API, so we might be able to wait with concomittantly "serious" documentation.

[linzjax]

drfdocs' documentation isn't great (ironically). I had to dig around in their code because docstrings appear in their demo.

[ian-ross]

For reference, someone wrote a thing to autogenerate Swagger docs from DRF code: http://django-rest-swagger.readthedocs.org/en/latest/#

[linzjax]

I tried that out yesterday and it didn't seem to like the way the api was set up. It would only display /account/ and /organizations/ headers, but none of the actual end points. I can mess around with it some more to see if there's a way to fix it.

[ian-ross]

Huh. Do you see any error messages, either coming from the Django dev server, or in the browser console? Or are things just silently not appearing?

[linzjax]

Silently not appearing. Which was odd because if you looked at the 'raw' option, everything was there.

[ian-ross]

OK, don't worry about that. Let's see if you can get docstrings working with DRF Docs. If you can, that will be good enough for now. (If not, we'll think about it again. But I bet you can.)

[wonderchook]

Just wanted to echo "good enough" as far as API docs. We need to have API docs, but as @ian-ross mentioned I just don't see people extensively using them for some time.

[ian-ross]

If you have trouble with getting docstrings to work, give me or @oliverroick a shout. It looks as though they ought to work (as you say, they work in the demo). I just tried it out with Python 3.5.1, Django 1.9.2 and DRF 3.3.3 (what we're using in the platform) and the demo worked fine.

[linzjax]

They seem to work just fine:

[ian-ross]

Looks good. Do you want to set that all up and make a PR to incorporate the DRF Docs into the platform? (If you have any questions about the usual squash-rebase-PR dance, let one of us know.)

[linzjax]

It's still stripping /v1/ out of the endpoints, so the 'live' part of it doesn't work. It's also displaying some endopints (that look like their coming from djoser) twice. But if it's okay that it's a little odd right now, I can go ahead and do the pr dance.