Swagger documentation in Dango

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

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

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

Installation

pip install drf-yasg

django配置可以参照​​https://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):

【本文转自：防御ddos http://www.558idc.com/stgf.html提供,感谢支持】