为Django-REST-framework的@action中的每个方法添加特定文档字符串

Question

在Django-REST框架中，我在一个ViewSet里使用@action装饰器为几个方法添加了额外的路由操作。我想给每个方法写不同的文档说明，但显然这样做不太行。有没有什么好主意？

@action(methods=['GET', 'POST', 'DELETE'])
def followers(self, request, player):

    if request.method == 'GET':
        """
        Get the players who follow this player
        """
        [...]

    elif request.method == 'POST':
        """
        Follow this player
        """
        [...]

    [...]

生成的文档在Swagger上显示：https://i.stack.imgur.com/8kzUw.png

Answer 1

每个方法只能有一个文档字符串（docstring），所以通常你有两个选择：

1. 你可以给followers方法定义一个文档字符串，里面解释这个方法是怎么工作的。如果你确定不同的HTTP方法的业务逻辑不太复杂，这个选择就很合适。

2. 为不同的请求类型定义独立的方法，这样每个方法就可以有自己的文档字符串。这种方式可以让每个方法内部的逻辑尽量简单。

你也可以考虑返回一个对象，这个对象里面有不同的方法来表示HTTP方法，并根据需要调用它们。