How to dinstinctly document possible REST actions in ViewSet docstring?

Question

The DRF docs mention this:

Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the the list and retrieve views, use docstring sections as described in Schemas as documentation: Examples.

But the link is bad, and the similar link, https://www.django-rest-framework.org/api-guide/schemas/, doesn't mention these "sections."

How do I distinctly document my different possible REST actions within my single Viewset when it is composed like,

class ViewSet(mixins.ListModelMixin,                                            
              mixins.RetrieveModelMixin,                                        
              mixins.CreateModelMixin,                                          
              mixins.UpdateModelMixin,                                        
              ):       

Yearly

Answer 1

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.

Zoochemistry

This is the correct answer to the original question. – Housewarming

Wow, after searching for a while I was convinced there wasn't a simple way to do this without messing with schemas. Thank you! – Pittsburgh

Unfortunately this doesn't work for me with ReadOnlyModelViewSet. – Arevalo

It's work but only descriptions on each method, string "General ViewSet description" not present in each method description. – Phototransistor

Answer 2

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.

Condon

Thank you, I was imagining some kind of special formatting in the docstring of the class. – Yearly