django-rest-swagger 如何记录 API答案

【问题标题】：django-rest-swagger how to document the APIsdjango-rest-swagger 如何记录 API
【发布时间】：2016-12-06 02:44:21
【问题描述】：

我现在将 DRS 用于我的简单 django REST API，虽然它并不完美，但到目前为止它一直是一个很棒的库。但是有一些问题

我正在使用

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 确实提供了此类功能，请提供帮助。

谢谢，

【问题讨论】：

也许我的回答here会对你有所帮助
回复similar question

标签： django-rest-framework swagger

【解决方案1】：

既然你在做一个帖子，添加终点简短描述这就是我要做的

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

或者在你的 UserViewSet 类中：

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

这可能会回答问题 1

【讨论】：

【解决方案2】：

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

【讨论】：