Django项目生成api文档 之 swagger

Django Rest Swagger生成api文档

1.简介

1.1 swagger

Swagger是一个框架，在项目中使用swagger框架，使其生成一个API文档供前端查看。

1.2 django-swagger

根据前面swagger的定义，可以猜出，django-swagger即是让django项目产生相应的API文档。

2 版本

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

3 搭建框架——新建django项目

3.1 创建app

例：
     Step1：创建了一个apps，并在其下也创建了一个python package——project，并且delete project的_init_.py文件）

    Step2：将python包转成app——python manage.py startapp 包名 路径

3.2 设置setting配置文件

     Step1：在INSTALLED_APPS中加入app和两个包

     Step2：配置session存储

3.3 设置models

     Step1：设置apps/project/models

3.4 添加serializers.py

     Step1：在apps/project下添加serializers.py文件（如果想要使用try it out的试用接口按钮的话）

提示：fields的说明

fileds=__all__ #展示model中所有的字段
fileds=('name',)  #展示model中的name字段
# 注意：必须含有主键字段

3.5 配置urls.py

     Step1：配置apps/project/urls.py

     Step2：配置autoTestApidoc/urls.py

3.6 在view.py中设置api文档的页面内容

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')

设置不同的location效果展示

1）header,query,formData

2）form

注意：

1. 注释支持 Markdown
2. 新版的swagger取消了YAML，不再支持在注释中添加responses和request的参数等
3. 可以在如下包内的文件中修改页面的样式等信息
4. django

3.7 效果展示

3.8 问题

1. 没有找到可以在Responses添加code和description的动态方法，暂时只能在如下位置修改，产生静态的。
   
2. 页面的效果不怎么满意，达不到自定义效果，还是低版本支持的YAML，比较灵活，不过，它低版本的不支持django2.1 python3.7 ，只支持到django 2.0以下。
3. 求助各位大佬，希望能有定义页面的方法。

4 搭建框架——官网编辑器

另外，发现了一种在线编辑器：https://swagger.io/docs/swagger-tools/
它似乎不支持自动生成django的内容，其他类型的倒是可以。

---

参考链接：
[1] : https://www.jianshu.com/p/e748fe520f2d