How to dinstinctly document possible REST actions in ViewSet docstring?

I came here from Google after spending ages tracking this down. There is indeed a special formatting of the docstring to document individual methods for ViewSets.

The relevant example must have been removed from the documentation at some point but I was able to track this down in the source. It is handled by the function get_description in https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/coreapi.py

The docstring format is based on the action names (if view.action is defined):

"""
General ViewSet description

list: List somethings

retrieve: Retrieve something

update: Update something

create: Create something

partial_update: Patch something

destroy: Delete something
"""

If view.action is not defined, it falls back to the method name: get, put, patch, delete.

Each new section begins with a lower case HTTP method name followed by colon.


Each mixin have specific method like mixins.ListModelMixin use list method. So you can specify distinctly documentation like this;

    class ViewSet(mixins.ListModelMixin,                                            
                  mixins.RetrieveModelMixin,                                        
                  mixins.CreateModelMixin,                                          
                  mixins.UpdateModelMixin,):
        queryset = Model.objects.all()
        serializer_class = Serializer
        ...


        def list(self, request, *args, **kwargs):
            """ 
            This endpoints returns list of objects...
            """
            return super(ViewSet, self).list(request, *args, **kwargs)

and if you don't have any specific logic then call the super() method.

  • mixins.RetrieveModelMixin use retrieve
  • mixins.CreateModelMixin use create and
  • mixins.UpdateModelMixin use update methods.