How to create Swagger documentation for a Django app?

本文共计860个文字，预计阅读时间需要4分钟。

使用`rest_framework.views.APIView`模块，Django提供了高效的RestAPI开发工具。然而，RestAPI文档往往较为复杂。以下是如何制定简洁明了的RestAPI文档，以有效表达endpoint、input和response，以及版本管理：

1. endpoint清晰定义： - 使用简洁的URL路径，如`/api/resource/`。 - 为每个endpoint提供明确的描述，说明其功能。

2. input参数明确： - 列出所有必需和可选的input参数。 - 使用JSON格式示例展示输入数据结构。

3. response结构化： - 描述成功和错误响应的状态码。 - 使用JSON格式示例展示响应数据结构。

4. 版本管理： - 为API版本分配明确的编号，如`/api/v1/resource/`。 - 在文档中明确每个版本的变更和兼容性。

示例文档：

markdownAPI 文档

Endpoint: /api/v1/resource/

获取资源列表- URL: `/api/v1/resource/`- Method: `GET`- Input: - `limit`: int, 资源数量限制，默认为10。 - `offset`: int, 起始索引，默认为0。- Response: - Success (200): json { count: 10, next: /api/v1/resource/?limit=10&offset=10, previous: null, results: [ { id: 1, name: Resource 1 }, // ... 更多资源 ] } - Error (400): json { detail: Invalid input parameters. }

创建新资源- URL: `/api/v1/resource/`- Method: `POST`- Input: - `name`: str, 资源名称。- Response: - Success (201): json { id: 1, name: Resource 1 } - Error (400): json { detail: Invalid input parameters. }

版本管理- 当前版本：v1- 未来版本将提供向后兼容性说明。

通过这种方式，可以确保RestAPI文档简洁明了，易于理解和使用。

利用rest_framework.views.APIView模块，Django提供了非常有效的RestAPI开发。但是RestAPI文档是一个比较棘手的问题。

• 怎么制定简洁明了的RestAPI文档去有效的表达endpoint, input and response
• 怎么版本管理文档开发、
• 怎样去保证代码和文档的一致性

drf-swagger提供了很好的解决方案， 通过decorator的形式和RestAPI方法绑定的一起。下面是我的一些理解。

Installation

pip install drf-yasg

django配置可以参照​​drf-swagger.readthedocs.io/en/1.2.0/readme.html​​

Query Parameter Request

这个适用GET method

from drf_yasg.utils import swagger_auto_schema
from rest_framework.decorators import api_view

@swagger_auto_schema(
operation_description="get latest docker image version",
operation_id='get latest docker version',
method='get',
manual_parameters=[openapi.Parameter(
name='repository',
in_=openapi.IN_QUERY,
required=True,
type=openapi.TYPE_STRING,
description='repository name'
)]
tags=['pr']
)
@api_view(['GET'])
def get_latest_docker(request):

• manual_parameters: 参照​​openapi.Parameter​​
• type: 参照​​openapi.TYPE​​

Body Request

适用于PUT， POST methods

@swagger_auto_schema(
operation_description="insert pull request record",
operation_id='insert pull request record',
request_body=openapi.Schema(
type=openapi.TYPE_OBJECT,
required=['repository', 'number'],
properties={
'repository': openapi.Schema(
type=openapi.TYPE_STRING,
description='repository name'
),
'number': openapi.Schema(
type=openapi.TYPE_NUMBER,
description='pull request number'
)
},
),
tags=['pr'])
def post(self, request):

• request_body：参照​​openapi.Schema​​
• properties：同样参照​​openapi.Schema​​

如果比较复杂的json data

@swagger_auto_schema(operation_description="insert pull request record",
operation_id='insert pull request record',
request_body=openapi.Schema(
type=openapi.TYPE_OBJECT,
properties={
'dependency': openapi.Schema(
type=openapi.TYPE_ARRAY,
items=openapi.Schema(
type=openapi.TYPE_OBJECT,
properties={
'name': openapi.Schema(type=openapi.TYPE_STRING, description='module name'),
'version': openapi.Schema(type=openapi.TYPE_STRING, description='module version')
},
description='list of package dependencies'
),
description='python package dependencies'
},
),
tags=['pr']
)
def post(self, request):

• 如果是array，就用​​type=openapi.TYPE_OBJECT​​​和​​items​​
• 如果是dict， 就用​​type=openapi.TYPE_OBJECT​​​和​​properties​​

代码和文档分离

可以放到不同文件管理

insert_doc = dict(operation_description="insert pull request record",
operation_id='insert pull request record',
request_body=openapi.Schema(
type=openapi.TYPE_OBJECT,
properties={
'dependency': openapi.Schema(
type=openapi.TYPE_ARRAY,
items=openapi.Schema(
type=openapi.TYPE_OBJECT,
properties={
'name': openapi.Schema(type=openapi.TYPE_STRING, description='module name'),
'version': openapi.Schema(type=openapi.TYPE_STRING, description='module version')
},
description='list of package dependencies'
),
description='python package dependencies'
},
),
tags=['pr']
)


@swagger_auto_schema(**insert_doc)
def post(self, request):