关于Flask 项目中使用 Swagger 的探索

引言：

• 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: 别名