CODEWITHSUNDEEP
django-rest-frameworkopenapidrf-yasg
rrauenza
rrauenza

Reputation: 6993

How to dinstinctly document possible REST actions in ViewSet docstring?

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,                                        
              ):

Upvotes: 13

Views: 2490

Answers (2)

user12233657
user12233657

Reputation: 246

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.

Upvotes: 23

uedemir
uedemir

Reputation: 1714

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.

Upvotes: 8

Related Questions