django-rest-swagger how to document the APIs

Question

I am now using DRS for my simple django REST APIs and although its not perfect, it has been a great library so far. But having a few issues

I am using

django-rest-swagger==2.0.3

And my api-doc looks like this

Issue #1: I can't find a way to add some documentation, I tried putting YAML under my class based viewset action methods, not working. Put docstring under ViewSet class directly, no luck. Then I saw that in the latest DRS release, 2.0 change mentioned YAML docstring has been deprecated.

So how do I provide something like 1. Endpoint short description 2. parameter description and probably a sample format

Issue #2: How do I specify which parameter is mandatory.

For example, I have an action in my UserViewSet

    @detail_route(methods=['post'], url_path='set-password')
@AssertInRequestBody(['password'])
def set_password(self, request, pk):
    """
    set user password
    """
    user = User.objects.get(pk=pk)
    json_data = get_json_data(request)
    user.set_password(json_data['password'])
    user.save()
    return DefaultResponse(_('Successfully set password for user %s'
                             % user.email), status.HTTP_200_OK)

And I want it to be a POST operation and there will be a password in the request body. I can't figure out a way to document that.

This applies to other operations, I guess right now DRS is simply looking at the model definition and serializer definition to determine which parameter is mandatory, which doesn't quite make sense to me.

I feel that DRS should provide some sort of decorators so that we can easily add corresponding documentation to an action method.

But maybe I am wrong, please help if DRS does provide such functionalities.

Thanks,

maybe my answer [here](http://stackoverflow.com/questions/38542690/django-rest-framework-swagger-2-0?answertab=active#tab-top) would help you — bitnik, Aug 04 '16 at 08:07
answered to a [similar question](http://stackoverflow.com/a/39393093/929164) — Daniel Dror, Sep 08 '16 at 14:08

score 1 · Answer 1 · answered Oct 13 '17 at 06:54

1

May be this is so late, but just for some help, this doc explains django rest swagger 2 integration step by step: Django Rest Swagger 2 comprehensive documentation

answered Oct 13 '17 at 06:54

Haziq

2,048
1
16
27

score -1 · Answer 2 · answered Sep 06 '17 at 10:44

Since you are doing a post, to add the end point short description this is what I would do

def set_password(self, request, pk):
    """
    create:
        set user password
    """
    ...

Or in your UserViewSet class:

class UserViewSet(...)
    """
    set_password:
        set user password
    """

That may answer question 1

django-rest-swagger how to document the APIs

2 Answers2