flask 接口文档自动化

首先可以先去了解下 Swagger ，这个第三方库....这是flask的一个库，可以很好的生成flask的文档。还是比较好用的。

安装依赖：
使用 pip install flasgger 安装 flasgger 库。
编写代码：
python
from flask import Flask
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/users')
def get_users():
    """
    获取所有用户信息
    ---
    responses:
      200:
        description: 成功返回用户信息
    """
    return "All users"

if __name__ == '__main__':
    app.run(debug=True)
访问文档：
启动 Flask 应用后，访问 http://localhost:5000/apidocs/（端口根据实际情况调整）查看 Swagger 文档。

这只是个大概的例子....

看下，实际的例子：

@abnormal_blockage.route('/stop')
def stop():
    """
    执行异常阻断
    ---
    tags:
     - 异常阻断tool
    summary: 执行异常阻断
    description: 返回是否成功阻断了操作
    responses:
     200:
      description: 异常阻断
      schema:
       type: object
       properties:
        result:
         type: boolean
         description: 阻断结果
     400:
      description: 请求参数错误
    """
    value = random.randint(0, 1)
    if value:
        result = True
    else:
        result = False
    return jsonify(result=result)

这是一个get请求的....

@alarm_notification.route('/', methods=['POST'])
def send_emails():
    """
    发送告警通知邮件
    ---
    tags:
      - 告警通知tool
    summary: 发送告警通知邮件
    description: 通过发邮件接口发送告警通知邮件。
    parameters:
      - name: subject
        in: body
        type: string
        required: true
        description: 邮件主题
      - name: message
        in: body
        type: string
        required: true
        description: 邮件正文
      - name: to
        in: body
        type: string
        required: true
        description: 收件人地址
      - name: cc
        in: body
        type: string
        required: true
        description: 抄送人地址
    responses:
      200:
        description: 邮件发送成功
        schema:
          type: object
          properties:
            result:
              type: boolean
              description: 邮件是否成功发送
      400:
        description: 请求参数错误
      500:
        description: 内部服务器错误
    """
    email_msg = json.loads(request.get_data().decode())

这是一个post请求的.

其实重点就在于函数里的说明文档部分，这东西写好，然后就能实现接口文档的自动化了....

直接访问 http://localhost:5000/apidocs/ 就可以....

这个界面的话，还可以直接进行测试用：

这里点开以后，还可以直接测试，并可以看到测试结果

整体还是好用的，就是有点费人.....写函数的时候，得写一大堆的 yml 格式的说明。