Flasgger：为 Flask API 自动生成 Swagger 文档

Flasgger：为 Flask API 自动生成 Swagger 文档

Flasgger 是一个用于 Flask 项目的 API 文档工具，在 GitHub 上获得了 3,741 个 Star：

Flasgger 是一个 Flask 扩展，功能是从 Flask 视图中提取 OpenAPI 规范，并内置 Swagger UI 供开发者查看和测试 API 接口。

Flasgger 支持多种方式定义 API 规范。开发者可以在函数 docstring 中编写 YAML 格式的规范，Flasgger 会在应用启动时解析。也可以通过 @swag_from 装饰器引入 YAML 文件或 Python 字典。对于使用 Marshmallow 的项目，Flasgger 支持用 Marshmallow Schema 作为规范来源。

Flasgger 还提供了请求数据验证功能。收到 POST、PUT、PATCH 请求时，Flasgger 会根据定义好的规范校验请求体。数据不符合要求时，返回 400 状态码和错误信息。验证规则和文档规范使用同一套定义，不需要重复编写。

验证逻辑支持自定义。开发者可以传入自己的验证函数替代默认的 python-jsonschema，自定义函数接收数据和校验模式两个参数，验证失败时抛出异常即可。错误处理逻辑同样可以自定义，由开发者决定如何响应校验失败的情况。

Flasgger 与 Flask-RESTful 兼容，支持在 Resource 类中直接使用。它也支持 Flask 的 MethodView，能配置解析外部 YAML 文档目录。开发者按端点名称和方法名组织 YAML 文件，Flasgger 会加载匹配的内容。

在 Swagger UI 方面，Flasgger 内置了 Swagger UI 2 和 3。默认使用版本 2，通过配置可切换到版本 3。Swagger UI 的模板也可自定义，覆盖项目中的 templates/flasgger/index.html 文件即可。

Flasgger 支持 OpenAPI 3.0 规范，这是一个实验性功能。通过设置配置项启用后，可以使用 requestBody 和 callbacks 等特性。

安装 Flasgger 通过 pip 命令：

pip install flasgger

如需使用 Marshmallow Schema，额外安装：

pip install marshmallow apispec

以下是一个基于 docstring 的示例：

from flask import Flask, jsonify
from flasgger import Swagger

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

@app.route('/colors/<palette>/')
def colors(palette):
    """返回调色板中的颜色列表
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    responses:
      200:
        description: 颜色列表
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}
    return jsonify(result)

app.run(debug=True)

运行后访问 /apidocs/ 即可看到 Swagger 文档界面。界面上列出所有已注册的 API 端点，支持填写参数并发送请求。

Flasgger 提供了自定义选项。开发者可以修改文档路径、禁用 Swagger UI、设置 API 信息标题和版本号等。对于部署在反向代理后的应用，Flasgger 提供了 LazyString 机制，可在运行时根据请求上下文调整配置，比如识别 https 协议。

Flasgger 提供了一组测试用例和示例应用，源码中的 examples 目录包含多种使用场景的代码。开发者可以通过这些示例了解功能的使用方法。项目还包含一个在线演示应用，部署在 PythonAnywhere 上，可以直接体验功能。