使用Flasgger生成Swagger文档

前言

Flasgger 可以为 Flask 路由自动生成 Swagger UI 文档。

安装：

python -m pip install flasgger

示例

from flask import Flask, jsonify, request
from flasgger import Swagger, swag_from

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


@app.get("/items/<int:item_id>")
@swag_from(
    {
        "parameters": [
            {
                "name": "item_id",
                "in": "path",
                "type": "integer",
                "required": True,
            }
        ],
        "responses": {
            200: {"description": "查询成功"},
            404: {"description": "不存在"},
        },
    }
)
def get_item(item_id):
    if item_id != 1:
        return jsonify({"code": 404, "msg": "not found"}), 404
    return jsonify({"code": 200, "data": {"id": 1, "name": "apple"}})

访问 http://127.0.0.1:5000/apidocs/ 查看 Swagger UI。

提示

也可用 docstring 的 YAML 注释（@swag_from("docs/get_item.yml")）方式描述接口。更现代的替代方案：flask-restx（见 flask-restplus 目录）或 APIFairy。