django-rest-swagger如何记录API

Question

我现在正在为我的简单django REST API使用DRS，尽管它并不完美，但到目前为止它已经是一个很棒的库了。但是有几个问题

我正在使用

django-rest-swagger==2.0.3

我的api-doc看起来像这样

​

​

问题#1:我找不到一种方法来添加一些文档，我尝试将YAML放在我的基于类的视图集操作方法下，但不起作用。将docstring直接放在ViewSet类下，没问题。然后我发现在最新的DRS版本中，2.0提到的YAML文档字符串已经被弃用了。

那么我该如何提供类似于1.端点简短描述2.参数描述以及可能的示例格式

问题#2:如何指定哪个参数是必需的。

例如，我的UserViewSet中有一个操作

    @detail_route(methods=['post'], url_path='set-password')
@AssertInRequestBody(['password'])
def set_password(self, request, pk):
    """
    set user password
    """
    user = User.objects.get(pk=pk)
    json_data = get_json_data(request)
    user.set_password(json_data['password'])
    user.save()
    return DefaultResponse(_('Successfully set password for user %s'
                             % user.email), status.HTTP_200_OK)

我希望它是一个POST操作，并且在请求正文中会有一个密码。我想不出一种方法来记录这件事。

这也适用于其他操作，我猜现在DRS只是简单地查看模型定义和序列化程序定义，以确定哪个参数是必需的，这对我来说没有太大意义。

我觉得DRS应该提供某种装饰器，这样我们就可以很容易地向操作方法中添加相应的文档。

但也许我错了，如果DRS确实提供了这样的功能，请帮助。

谢谢,

Answer 1

可能为时已晚，但这只是为了获得一些帮助，本文档逐步解释了django rest swagger 2集成：Django Rest Swagger 2 comprehensive documentation

Answer 2

由于你正在做一篇文章，为了添加端点简短的描述，这就是我要做的

def set_password(self, request, pk):
    """
    create:
        set user password
    """
    ...

或者在您的UserViewSet类中：

class UserViewSet(...)
    """
    set_password:
        set user password
    """

这可能回答了问题1