Flasgger为Flask应用生成优雅的API文档

Flasgger简介

Flasgger是一个专为Flask框架设计的扩展库，它通过解析代码注释或外部配置文件，自动生成符合OpenAPI规范的API文档，并集成Swagger UI界面：

• 文档自动化：基于Python docstring自动生成实时更新的API文档
• 交互式测试：直接在文档页面发送请求并查看响应
• 数据验证：支持YAML/JSON Schema/Marshmallow多种验证方式
• RESTful支持：无缝兼容Flask-RESTful框架

其核心价值在于将API设计与文档维护成本降低80%，特别适合需要频繁迭代API的中大型项目。

安装配置：三步快速上手

基础安装

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate.bat  # Windows

# 安装Flasgger和Flask
pip install flask flasgger

最小化应用示例

from flask import Flask
from flasgger import Swagger

app = Flask(__name__)
Swagger(app)  # 初始化扩展

@app.route('/hello')
def hello():
    """最简API示例
    ---
    tags:
      - 基础功能
    responses:
      200:
        description: 返回欢迎消息
    """
    return "Hello World!"

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

访问 http://localhost:5000/apidocs 即可看到自动生成的Swagger界面。

基本用法

标准YAML注释规范

@app.route('/user/<int:id>')
def get_user(id):
    """获取用户信息
    ---
    tags:
      - 用户管理
    parameters:
      - name: id
        in: path
        type: integer
        required: true
        description: 用户ID
    responses:
      200:
        description: 返回用户对象
        schema:
          id: User
          properties:
            id:
              type: integer
            name:
              type: string
      404:
        description: 用户不存在
    """
    # 实际业务逻辑
    return {"id": id, "name": "张三"}

多HTTP方法支持

@app.route('/data', methods=['GET', 'POST'])
def data_handler():
    """多功能端点示例
    ---
    get:
      summary: 获取数据列表
      responses:
        200:
          description: 返回数据数组
    post:
      summary: 创建新数据
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/DataItem'
      responses:
        201:
          description: 创建成功
    """
    if request.method == 'GET':
        return ["data1", "data2"]
    elif request.method == 'POST':
        return "Created", 201

核心参数配置详解

通过Swagger()初始化参数或app.config进行配置：

完整配置示例：

swagger_config = {
    "headers": [],
    "specs": [{
        "endpoint": 'apispec_1',
        "route": '/apidocs.json',
        "rule_filter": lambda rule: True  # 过滤规则
    }],
    "static_url_path": "/flasgger_static",
    "swagger_ui": True,
    "specs_route": "/apidocs/"
}

app.config['SWAGGER'] = {
    'title': '用户管理系统',
    'version': '2.3.0',
    'uiversion': 3,
    'openapi': '3.0.0'
}

Swagger(app, config=swagger_config)

高级配置技巧

自定义认证集成

from flask import request
from flasgger import Swagger

# 初始化时添加安全定义
template = {
    "securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    }
}

swagger = Swagger(app, template=template)

# 在API定义中添加安全要求
@app.route('/protected')
def protected_resource():
    """受保护资源
    ---
    security:
      - Bearer: []
    """
    auth_header = request.headers.get('Authorization')
    if not auth_header or auth_header.split()[0] != 'Bearer':
        return "Unauthorized", 401
    return "Protected Data"

多规格文档管理

# 定义多个API规范
swagger_config = {
    "specs": [
        {
            "version": "1.0",
            "title": "旧版API",
            "endpoint": 'v1_spec',
            "route": '/v1/apidocs.json'
        },
        {
            "version": "2.0",
            "title": "新版API",
            "endpoint": 'v2_spec',
            "route": '/v2/apidocs.json'
        }
    ]
}

# 通过不同路由访问不同文档
@app.route('/v1/apidocs')
def v1_docs():
    return redirect('/v1/apidocs.json')

@app.route('/v2/apidocs')
def v2_docs():
    return redirect('/v2/apidocs.json')

深度集成Marshmallow

from marshmallow import Schema, fields

class UserSchema(Schema):
    id = fields.Int(required=True)
    name = fields.Str()
    email = fields.Email()

# 在视图中使用
@app.route('/user', methods=['POST'])
@swag_from({
    'parameters': [
        {
            'in': 'body',
            'name': 'body',
            'schema': UserSchema()
        }
    ]
})
def create_user():
    data = UserSchema().load(request.json)
    # 处理业务逻辑
    return data, 201