如何使用 Django REST Swagger 记录 pk 参数（或其他路径参数）？

【问题标题】：How can I document the pk parameter (or other path parameters) with Django REST Swagger?如何使用 Django REST Swagger 记录 pk 参数（或其他路径参数）？
【发布时间】：2016-02-05 10:01:40
【问题描述】：

有没有办法记录 Django REST Framework 自动生成的 pk 参数（通过扩展 ViewSet）？

ViewSet 中的示例函数：

class MyViewSet(viewsets.ViewSet):
    @detail_route(url_path='mypath')
    def myapi(self):
        """
            first_param -- Param 1
        """
        pass

如果我在 YAML 文档字符串中添加 pk 参数，我会得到一个重复。

【问题讨论】：

标签： python django rest django-rest-framework swagger

【解决方案1】：

pk 参数（或任何其他路径参数）可以使用 YAML 文档字符串记录，如 documentation of Django REST Swagger 中所述。属性列表可以参考Swagger documentation。

请注意，您必须为路径参数指定paramType: path。为避免重复出现在您的 api-docs 中，您可以指定 parameters_strategy: replace，如 here 所述。

例子：

@detail_route(url_path='mypath')
def myapi(self, request, **kwargs):
    """
    Endpoint documentation.
    ---
        parameters_strategy: replace
        parameters:
            - name: pk
              description: "Primary Key"
              required: true
              type: string
              paramType: path
    """

【讨论】：