Documenting responses

['ju5t' via Django REST framework]

I'm trying to improve the documentation of our API. It took me a little
while to find out that `help_text` adds the description but apart from that
things are getting along as expected.

The only problem I have at the moment is that I would like to document the
responses, including the errors you may hit. There might be documentation
out there that I have missed, in which case I'm sorry for asking, but
perhaps someone can point me into the right direction?

[Jason]

have you looked at
http://www.django-rest-framework.org/topics/documenting-your-api/

you can add all that example info to the docstring of a view.
Alternatively, there's https://github.com/marcgibbons/django-rest-swagger/ and
apiary, which are two options you can use to document your API.

['ju5t' via Django REST framework]

Sorry, perhaps I should have posted what I have done already. We've been
running Swagger for a while already and are currently looking into the
default documentation options in DRF as they have been improving. The
documentation didn't answer my question unfortunately. I'm specifically
looking to document our responses.

I just found a discussion on Github about response schema's. That's
basically what I was looking for.

https://github.com/marcgibbons/django-rest-swagger/issues/583
https://github.com/encode/django-rest-framework/issues/4502

Apparently it did get mentioned in some 3.6 notes of DRF but never made it
into the release.

drf-yasg does support documenting response schema's but they don't support
AcceptHeaderVersioning. I guess we have not much choice but to document it
in docstrings for now. From the looks of it, 3.8 may see improved support
for this.

Post by Jason
have you looked at
http://www.django-rest-framework.org/topics/documenting-your-api/
you can add all that example info to the docstring of a view.
Alternatively, there's https://github.com/marcgibbons/django-rest-swagger/ and
apiary, which are two options you can use to document your API.

[Jason]

Hmm, ok. The extra info helps.

FWIW, at work, we're moving off Swagger for reasons not clear to me, and my
team mainly uses Apiary with some mkdocs stuff. So you could look into
those?

Post by 'ju5t' via Django REST framework
Sorry, perhaps I should have posted what I have done already. We've been
running Swagger for a while already and are currently looking into the
default documentation options in DRF as they have been improving. The
documentation didn't answer my question unfortunately. I'm specifically
looking to document our responses.
I just found a discussion on Github about response schema's. That's
basically what I was looking for.
https://github.com/marcgibbons/django-rest-swagger/issues/583
https://github.com/encode/django-rest-framework/issues/4502
Apparently it did get mentioned in some 3.6 notes of DRF but never made it
into the release.
drf-yasg does support documenting response schema's but they don't support
AcceptHeaderVersioning. I guess we have not much choice but to document it
in docstrings for now. From the looks of it, 3.8 may see improved support
for this.

Post by Jason
have you looked at
http://www.django-rest-framework.org/topics/documenting-your-api/
you can add all that example info to the docstring of a view.
Alternatively, there's
https://github.com/marcgibbons/django-rest-swagger/ and apiary, which
are two options you can use to document your API.