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

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,                                            
        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.