引言：
- Flask是一款流行的Python实现的Web开发微框架；
- Swagger是一款Restful接口的文档在线自动生成+功能测试功能软件
- 当下支持 Flask 和 Swagger 的工具大概如下：
- flask-swagger
- flasgger
- flask-restplus
综合比较了一下，flask-restplus 对框架入侵较大， flask-swagger 集成 Swagger-UI比较繁琐，故尝试使用 flasgger。
本文简单介绍了 flasgger 的用法，以及解决的痛点和带来的痛点。
使用方法
- 安装使用：
- 示例:
# 安装 flasgger==0.9.5
pip install flasgger==0.9.5
- 加载 swagger
# -*- coding: utf-8 -*-
from traffic import app
from flasgger import Swagger
app.ready()
if app.g.is_dev():
# 开发环境增加 swagger 文档,并且指定路由
swagger = Swagger(app, config={"specs_route": "/traffic/apidocs/"}, merge=True)
if __name__ == '__main__':
app.run('0.0.0.0', 3001, threaded=True)
- 在API中使用
@api.route('/member.current', perm_ids=[], methods=['GET'])
@swag_from('../../../../apidocs/member/current.yml') # 此处为文档地址，相对路径
def get_current_user():
"""
当前用户昵称及权限
:return:
"""
- 对应的文档说明(apidocs/member/current.yml)
tags:
- member
summary: "查询信息接口"
description: "接口描述"
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: 正确返回的格式
schema:
$ref: "#/definitions/resultDto"
400:
description: Bad request
401:
description: 未登录
403:
description: Forbidden
404:
description: Not found
500:
description: Internal Server Error
definitions:
resultDto:
type: "object"
properties:
code:
type: "string"
default: "000000"
message:
type: "string"
default: "成功"
payload:
type: "object"
properties:
role_ids:
type: "array"
items:
$ref: '#/definitions/int_format'
member_id:
type: "integer"
name:
type: "string"
origin_member_name:
type: "string"
perm_keys:
type: "array"
items:
$ref: '#/definitions/int_format'
int_format:
type: "integer"
- 功能
- API 文档：说明了 Api 接口的基本信息，请求信息，返回信息
- API调试：类似 postman,自动填充参数类型和返回信息，能做基础参数验证。较之 postman 用户体验更佳
- 验证参数格式类型，校验更加严谨
使用 Swagger 的目的：
- 提升API的质量，方便开发进行自测
- 前端某些框架可自动根据 Swagger 生成或优化代码，提升效率
痛点：
- 严谨的规范给工程师带来不适，简单的接口或许会花费更多的时间来维护 swagger
- 工程师需要花费学习成本
-
需要调整现有的工作模式
- 原有模式： 设计阶段后，开发简单快速出一份API文档给前端，然后进行开发。双方交涉较少。
- 新的模式：设计阶段后，开发需要花时间整理详细的 Swagger 格式接口文档。开发需要部署 swagger 环境，交付前端，进行开发。API 文档流程加长了
附录：swagger yml 文件简单规则示例(https://blog.csdn.net/u010466329/article/details/78522992)，具体查阅官方文档
- GET 接口
#接口概要
summary: 查询所有用户信息
#接口描述
description: 查询出所有用户的所有信息，用户名，别名
#标签，方便快速过滤出User相关的接口
tags:
- User
parameters:
#上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型为path
- name: id
in: path
description: 要查询的用户的用户名,它是唯一标识
required: true
type: string
#返回值描述，必要自动
responses:
#返回的http状态码
200:
description: 所有用户信息或者用户的集合信息
#描述返回值
schema:
#返回值格式，可选的有array,integer,string,boolean
type: array
#针对array,每个条目的格式,type定义为array．必要填写items
items:
#引用在definitions下定义的Users
$ref: '#/definitions/User'
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
- POST 接口
description: 注册一个用户
#请求参数
parameters:
#参数key
- name: username
#传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
#body表示http头承载参数(body只能有一个,有body不能在有其他的)
in: formData
#参数描述
description: 用户名，不能使用已经被注册过的
#参数是否必要，默认false
required: true
#参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
type: string
- name: password
in: formData
description: 用户登陆密码，加密传输，加密存储
required: true
type: string
- name: alias
in: formData
type: string
description: 用户别名
#非必要字段
required: false
responses:
#返回的http状态码
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
- 定义model信息
definitions:
User:
#值类型
type: object
#定义属性
properties:
#属性名
id:
#类型
type: string
#描述
description: 用户的唯一id
username:
type: string
description: 用户名
alias:
type: string
description: 别名
