API Documentation

[nziebart]

It would be nice to have documentation for each API endpoint. Something like Django REST Swagger could be a good candidate: http://www.django-rest-framework.org/topics/documenting-your-api/. I'm not sure how difficult it is to integrate.

We should show at least the following for each method:

• HTTP Method
• URL path
• Request parameters
• Response data format (or point to the class that will be assigned to the data property)
• Possible error codes and descriptions

[williamflaherty]

To add to this, we should probably setup the django browseable API, it makes developing a lot easier. I think @Mimimiel knows how to do that.

[Mimimiel]

The browsable API is already up. I created a brief wiki on the subject. To that effect, a really, really bare bones documentation is on each page. We can either flesh out the documentation using just DRF or something like Django REST Swagger like you mentioned Nathan. I don't think it will be hard to integrate and Django REST Swagger (can I petition to call it #DRFSwag?) would probably have the the most helpful experience.

[Mimimiel]

I played around with #DRFSwag extensively, but it is very limited because it doesn't support nested serialization. I will check out some other documentation solutions, but at a minimum I will beef up the default documentation with your five request items. I will also ensure there's a browsable root page so it is easy to find all endpoints.

[Mimimiel]

I did try a few options like #DRFSwag, but it didn't support nested json nicely. For now, we can just keep using the browsable API, but, lacking a 3rd-party package, it would be ideal to extend the base browsable API template in order to introspect into our serializers and dynamically pull out our error codes and messages.