Flasgger 文档生成完全教程：从零开始掌握 4 种规范定义方法-CSDN博客

Flasgger 文档生成完全教程：从零开始掌握 4 种规范定义方法

【免费下载链接】flasgger 项目地址: https://gitcode.com/gh_mirrors/fla/flasgger

Flasgger 是一款专为 Flask 应用打造的 API 文档生成工具，它能帮助开发者轻松创建符合 OpenAPI 规范的交互式 API 文档。本教程将带您从零开始，掌握 4 种实用的 API 规范定义方法，让您的 API 文档既专业又易用。

为什么选择 Flasgger？

在现代 API 开发中，清晰的文档是团队协作和用户体验的关键。Flasgger 作为 Flask 的扩展，具有以下优势：

自动生成：减少手动编写文档的工作量
交互式界面：提供直观的 API 测试环境
多规范支持：兼容 Swagger/OpenAPI 2.0 和 3.0
灵活集成：支持多种定义 API 规范的方式

Flasgger 生成的交互式 API 文档界面，支持在线测试 API 端点

准备工作：安装与基础配置

首先，确保您的环境中已安装 Python 和 pip。通过以下命令安装 Flasgger：

pip install flasgger

基础 Flask 应用集成 Flasgger 的示例代码：

from flask import Flask
from flasgger import Swagger

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

@app.route('/colors')
def colors():
    """
    获取颜色列表
    ---
    responses:
      200:
        description: 成功返回颜色列表
        schema:
          type: array
          items:
            type: string
    """
    return ['red', 'blue', 'green']

if __name__ == '__main__':
    app.run(debug=True)

方法一：使用装饰器内联定义（快速入门）

内联定义是最简单直接的方式，通过在路由函数的文档字符串中使用 YAML 格式定义 API 规范。

基本用法

@app.route('/colors/<palette>')
def colors(palette):
    """
    根据调色板获取颜色列表
    ---
    parameters:
      - name: palette
        in: path
        type: string
        required: true
        enum: ['rgb', 'cmyk']
    responses:
      200:
        description: 成功返回指定调色板的颜色列表
    """
    palettes = {
        'rgb': ['red', 'green', 'blue'],
        'cmyk': ['cyan', 'magenta', 'yellow', 'black']
    }
    return palettes.get(palette, [])

这种方式适合简单的 API 端点，规范与代码紧密结合，便于维护。

使用内联定义生成的 API 文档，显示参数和响应示例

方法二：从 YAML/JSON 文件加载规范（规范分离）

对于复杂的 API 规范，建议将其存储在单独的 YAML 或 JSON 文件中，保持代码整洁。

步骤 1：创建规范文件

创建 examples/username_specs.yml 文件：

parameters:
  - name: username
    in: path
    type: string
    required: true
responses:
  200:
    description: 成功返回用户信息

步骤 2：在代码中引用

from flask import Flask
from flasgger import Swagger

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

@app.route('/user/<username>')
@swag_from('username_specs.yml')
def user_profile(username):
    return f"User: {username}"

if __name__ == '__main__':
    app.run(debug=True)

通过 @swag_from 装饰器引用外部规范文件，支持指定 HTTP 方法：

@swag_from('user_specs.yml', methods=['GET', 'POST'])
def user_operations():
    pass

方法三：使用 Python 字典定义规范（动态生成）

对于需要动态生成的规范，可以使用 Python 字典来定义 API 规范。

基本示例

from flask import Flask
from flasgger import Swagger

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

colors_spec = {
    "parameters": [
        {
            "name": "palette",
            "in": "path",
            "type": "string",
            "required": True,
            "enum": ["rgb", "cmyk"]
        }
    ],
    "responses": {
        "200": {
            "description": "成功返回颜色列表"
        }
    }
}

@app.route('/colors/<palette>')
@swag_from(colors_spec)
def colors(palette):
    palettes = {
        'rgb': ['red', 'green', 'blue'],
        'cmyk': ['cyan', 'magenta', 'yellow', 'black']
    }
    return palettes.get(palette, [])

if __name__ == '__main__':
    app.run(debug=True)

这种方式适合需要根据条件动态调整的规范，例如从数据库加载参数选项。

方法四：使用 Swagger 配置对象（全局设置）

通过配置 Swagger 对象，可以设置全局 API 信息，并集中管理多个规范。

全局配置示例

from flask import Flask
from flasgger import Swagger

app = Flask(__name__)

swagger_config = {
    "headers": [],
    "specs": [
        {
            "endpoint": 'apispec_1',
            "route": '/apispec_1.json',
            "rule_filter": lambda rule: True,
            "model_filter": lambda tag: True,
        }
    ],
    "static_url_path": "/flasgger_static",
    "swagger_ui": True,
    "specs_route": "/swagger/"
}

swagger = Swagger(app, config=swagger_config)

@app.route('/colors')
def colors():
    """
    获取颜色列表
    ---
    responses:
      200:
        description: 成功返回颜色列表
    """
    return ['red', 'blue', 'green']

if __name__ == '__main__':
    app.run(debug=True)

通过这种方式，可以配置多个规范端点，支持版本控制和多文档管理。

高级技巧：规范合并与覆盖

Flasgger 支持规范的合并与覆盖，让您可以创建基础规范并在特定端点中扩展。

合并示例

base_spec = {
    "parameters": [
        {"name": "api_key", "in": "header", "type": "string", "required": True}
    ]
}

@app.route('/protected')
@swag_from(base_spec)
@swag_from({
    "responses": {
        "200": {"description": "受保护资源"}
    }
})
def protected_resource():
    pass

常见问题与解决方案

如何支持 OpenAPI 3.0？

在初始化 Swagger 时指定 openapi_version 参数：

swagger = Swagger(app, openapi_version='3.0.0')

如何添加自定义验证？

使用 @swag.validate 装饰器：

@swag.validate('User')
@app.route('/user', methods=['POST'])
def create_user():
    pass

如何隐藏 Swagger UI？

在配置中设置 swagger_ui=False：

swagger = Swagger(app, config={"swagger_ui": False})

总结

通过本教程，您已经掌握了 Flasgger 的四种规范定义方法：

内联定义：适合简单 API，代码与规范紧密结合
外部文件：适合复杂规范，保持代码整洁
字典定义：适合动态生成的规范
全局配置：适合多规范管理和全局设置

Flasgger 为 Flask 应用提供了灵活而强大的 API 文档解决方案，无论是小型项目还是大型应用都能轻松应对。开始使用 Flasgger，让您的 API 文档更加专业、易用！

要查看更多示例，可以参考项目中的 examples/ 目录，其中包含了各种使用场景的完整代码示例。

【免费下载链接】flasgger 项目地址: https://gitcode.com/gh_mirrors/fla/flasgger

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考