Swagger是一个框架,在项目中使用swagger框架,使其生成一个API文档供前端查看。
根据前面swagger的定义,可以猜出,django-swagger即是让django项目产生相应的API文档。
package | 版本 | 最新版本 |
---|---|---|
python | 3.7 | |
django | 2.1 | 3.0 |
django-rest-swagger | 2.2.0 | 2.2.0 |
djangorestframework | 3.8.2 | 3.10.3 |
coreapi | 2.3.3 | 2.3.3 |
例:
Step1:创建了一个apps,并在其下也创建了一个python package——project,并且delete project的_init_.py文件)
Step2:将python包转成app——python manage.py startapp 包名 路径
Step1:在INSTALLED_APPS中加入app和两个包
Step2:配置session存储
Step1:在apps/project下添加serializers.py文件(如果想要使用try it out的试用接口按钮的话)
提示:fields的说明
fileds=__all__ #展示model中所有的字段
fileds=('name',) #展示model中的name字段
# 注意:必须含有主键字段
Step2:配置autoTestApidoc/urls.py
from rest_framework.views import APIView
from apps.project.models import Project
from apps.project.serializers import ProjectSerializer
from rest_framework.schemas import AutoSchema
from rest_framework.renderers import *
from apps.common.apiResponse import ApiJsonResponse
from apps.common.code import CODE
class ProjectList(APIView):
"""
post:
Return the list of project
---
# 实现备注:
**获取项目列表信息**
# 参数信息
| 请求参数 | 类型 | 说明 | 是否必填 | 附加信息 |
| ---- | ---- | ---- | ---- | ---- |
| name | string | 项目名称 | N | 无 |
| page | int | 页数 | Y | 无 |
| page_size | int | 每页容量 | N | page_size=[10,20,50,100] |
| 响应参数 | 类型 | 说明 |
| ---- | ---- | ---- |
| code | int | 响应结果码 |
| msg | string | 响应结果信息 |
| data | JSON | 返回数据 |
## 响应code说明
| Code | Description |
| ---- | ---- |
| 0 | 成功 |
| 10000 | 参数非法 |
| 10004 | 获取数据失败 |
# 示例:
## request:
- body:
Example value:
{
'name': 'publishSystem',
'page': 1,
'page_size': 10
}
## response:
- body:
Example value:
{
"code": 0,
"msg": "\u6210\u529f",
"data": {
"list": [{
"id": 2,
"name": "publishSystem",
"desc": "-",
"status": true,
"create_time": "2019-10-25 10:52:50",
"modify_time": "2019-10-25 11:31:32",
"is_delete": false
}],
"count": 1
}
}
responses:
400:
description: "Invalid ID supplied"
404:
description: "Pet not found"
405:
description: "Validation exception"
"""
schema = AutoSchema(
manual_fields=[
coreapi.Field(name='url',required=False,location='header',description='url',type='string'),
coreapi.Field(name='id',required=False,location='query',description='test',type='integer',example=2),
coreapi.Field(name='name', required=False, location='form', description='名称',type="string",example="Token string"),
coreapi.Field(name='page', required=False, location='form', description='页码', type="integer",example=1),
coreapi.Field(name='page_size', required=False, location='form', description='每页容量', type='integer',example=10),
]
)
def post(self, request):
# serializer = ProjectSerializer(data=request.data)
# if serializer.is_valid():
# serializer.save()
return ApiJsonResponse(0,CODE['0'],request.data)
# return ApiJsonResponse(10004,CODE['10004'],request.data)
通过coreapi_Field中的location你可以设置任何参数,location有下列可选选项可以选:
location参数 | 说明 | 示例 | 示例补充 |
---|---|---|---|
path | 将参数放在URI中,后端取值的时候,使用path | /project/{project_id} | project_id 即为放入path的参数 |
query | 包含在URL查询参数中,使用request.query 取值,通常用于GET请求 |
coreapi.Field(name='id',required=False,location='query') 则url为http://127.0.0.1:8000/edit?id=2&&page=1 |
?id=2 为query |
form | 包含在请求body中,若多个参数都使用了location=form,则这些参数一起形成一个json对象,使用request.data 可以获取整个form的内容 |
coreapi.Field(name='name', required=False, location='form', description='名称',type="string") coreapi.Field(name=‘page’, required=False, location=‘form’, description=‘xx’, type=“integer”), coreapi.Field(name=‘page_size’, required=False, location=‘form’, description=‘每页容量’, type=‘integer’) |
form的内容为{“name”:“xxx”,“page”:xx,“page_size”:xx} |
formData | 包含在请求body中,和form类似 | coreapi.Field(name='name', required=False, location='formData', description='名称',type="string") ,coreapi.Field(name=‘page’, required=False, location=‘formData’, description=‘页码’, type=“integer”,example=1), coreapi.Field(name=‘page_size’, required=False, location=‘formData’, description=‘每页容量’, type=‘integer’,example=10) |
“name=sunny&page=1&page_size=10” |
header | 包含在请求头中,可以自定义参数 | coreapi.Field(name='id',required=False,location='header') |
另外,发现了一种在线编辑器:https://swagger.io/docs/swagger-tools/
它似乎不支持自动生成django的内容,其他类型的倒是可以。
参考链接:
[1] : https://www.jianshu.com/p/e748fe520f2d