如何在 ViewSet 文档字符串中明确记录可能的 REST 操作？

Question

DRF docs 提到这个：

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.

但是link不好，类似的link，https://www.django-rest-framework.org/api-guide/schemas/，没有提到这些"sections."

我如何不同地在我的单个视图集中记录我的不同可能的 REST 操作，当它像这样组成时，

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

Answer 1

每个 mixin 都有特定的方法，例如 mixins.ListModelMixin 使用 list 方法。所以你可以像这样明确地指定文档；

    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)

如果您没有任何特定逻辑，请调用 super() 方法。

mixins.RetrieveModelMixin 使用 retrieve
mixins.CreateModelMixin 使用 create 和
mixins.UpdateModelMixin 使用 update 方法。

Answer 2

我花了很长时间才从 Google 来到这里。确实有一种特殊的文档字符串格式来记录 ViewSets 的各个方法。

相关示例一定是在某个时候从文档中删除了，但我能够在源代码中找到它。它由 https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/coreapi.py

中的函数 get_description 处理

文档字符串格式基于操作名称（如果定义了 view.action）：

"""
General ViewSet description

list: List somethings

retrieve: Retrieve something

update: Update something

create: Create something

partial_update: Patch something

destroy: Delete something
"""

如果没有定义view.action，则回退到方法名：get、put、patch、delete.

每个新部分都以小写的 HTTP 方法名称开头，后跟冒号。

如何在 ViewSet 文档字符串中明确记录可能的 REST 操作？

How to dinstinctly document possible REST actions in ViewSet docstring?

django-rest-framework

openapi

drf-yasg