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
useretrieve
mixins.CreateModelMixin
usecreate
andmixins.UpdateModelMixin
useupdate
methods.