如何为现有Flask项目集成OpenAPI(Swagger)并生成文档及使用Swagger UI？

我来帮你梳理下把Flask项目和OpenAPI（Swagger）集成的具体步骤，目前社区里最常用、维护最活跃的两个工具是Flask-RESTX和Flask-OpenAPI3，我分别给你讲下操作流程，你可以根据现有项目的复杂度选择合适的方案：

方案一：使用Flask-RESTX（自带Swagger UI，适合重构API） #

Flask-RESTX是Flask-RESTPlus的分支，自带Swagger UI，能自动生成OpenAPI文档，还能帮你做请求/响应的数据校验。

1. 安装依赖 #

先通过pip安装Flask-RESTX：

pip install flask-restx

2. 改造现有路由（或新建API） #

你需要把普通的Flask路由改造成Flask-RESTX的**命名空间（Namespace）和资源（Resource）**结构，同时定义数据模型对应OpenAPI的Schema：

from flask import Flask
from flask_restx import Api, Resource, fields

# 初始化Flask app
app = Flask(__name__)

# 配置API的基础信息，这些会显示在Swagger UI顶部
api = Api(
    app,
    version='1.0',
    title='我的Flask项目API',
    description='基于OpenAPI规范的自动生成文档',
    doc='/swagger/'  # 指定Swagger UI的访问路径，默认就是/swagger
)

# 创建命名空间，用于分组API（比如用户模块、订单模块）
user_ns = api.namespace('users', description='用户相关的所有操作')

# 定义数据模型，对应OpenAPI中的Schema，用于请求校验和响应格式化
user_model = api.model('User', {
    'id': fields.Integer(readOnly=True, description='用户唯一ID'),
    'username': fields.String(required=True, description='登录用户名'),
    'email': fields.String(required=True, description='用户联系邮箱')
})

# 模拟数据库数据
mock_users = [
    {'id': 1, 'username': 'alice', 'email': 'alice@example.com'},
    {'id': 2, 'username': 'bob', 'email': 'bob@example.com'}
]

# 定义用户列表资源
@user_ns.route('/')
class UserList(Resource):
    @user_ns.doc('list_users')  # 标记API的ID，用于文档识别
    @user_ns.marshal_list_with(user_model)  # 用模型格式化响应
    def get(self):
        '''获取所有用户的列表'''
        return mock_users

    @user_ns.doc('create_user')
    @user_ns.expect(user_model)  # 用模型校验请求体
    @user_ns.marshal_with(user_model, code=201)  # 格式化响应并指定状态码
    def post(self):
        '''创建一个新用户'''
        new_user = api.payload
        new_user['id'] = max(u['id'] for u in mock_users) + 1
        mock_users.append(new_user)
        return new_user, 201

# 定义单个用户资源
@user_ns.route('/<int:user_id>')
@user_ns.param('user_id', '要查询的用户ID')
@user_ns.response(404, '用户不存在')
class UserDetail(Resource):
    @user_ns.doc('get_user_detail')
    @user_ns.marshal_with(user_model)
    def get(self, user_id):
        '''根据ID获取单个用户的详情'''
        user = next((u for u in mock_users if u['id'] == user_id), None)
        if not user:
            api.abort(404, '用户不存在')
        return user

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

3. 访问Swagger UI与导出OpenAPI定义 #

启动项目后，直接访问http://localhost:5000/swagger就能看到自动生成的交互式文档——你可以直接在页面上测试API，查看请求/响应格式。

如果需要导出OpenAPI的JSON定义，访问http://localhost:5000/swagger.json即可获取完整的规范文件。

方案二：使用Flask-OpenAPI3（兼容普通Flask路由，侵入性低） #

如果你不想大规模重构现有代码，Flask-OpenAPI3是更好的选择——它支持用装饰器快速给现有路由添加OpenAPI注解，还支持Pydantic做数据校验。

1. 安装依赖 #

pip install flask-openapi3

2. 给现有路由添加OpenAPI注解 #

下面是一个兼容普通Flask路由的示例：

from flask import Flask, request
from flask_openapi3 import OpenAPI, Info, Tag
from pydantic import BaseModel, EmailStr

# 初始化API，配置基础信息
info = Info(title='我的Flask项目API', version='1.0.0')
app = OpenAPI(__name__, info=info)

# 创建标签，用于分组API
user_tag = Tag(name='user', description='用户相关操作')

# 用Pydantic定义请求和响应模型
class UserCreate(BaseModel):
    username: str
    email: EmailStr  # 自动校验邮箱格式

class UserResponse(BaseModel):
    id: int
    username: str
    email: EmailStr

# 模拟数据库
mock_users = [{'id': 1, 'username': 'charlie', 'email': 'charlie@example.com'}]

# 普通Flask路由添加OpenAPI注解
@app.get('/users', tags=[user_tag], summary='获取用户列表', responses={'200': UserResponse})
def get_users():
    '''获取系统中所有用户的列表'''
    return mock_users

@app.post('/users', tags=[user_tag], summary='创建新用户', request_body=UserCreate, responses={'201': UserResponse})
def create_user(body: UserCreate):
    '''创建一个新用户，邮箱格式会自动校验'''
    new_user = body.dict()
    new_user['id'] = max(u['id'] for u in mock_users) + 1
    mock_users.append(new_user)
    return new_user, 201

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

3. 查看文档与导出定义 #

启动项目后，访问http://localhost:5000/swagger查看Swagger UI，或者访问http://localhost:5000/redoc查看更简洁的ReDoc文档。OpenAPI的JSON定义可以通过http://localhost:5000/openapi.json获取。

一些实用注意点 #

• 如果你的项目已经有大量普通Flask路由，可以先从新增的API开始用上述工具改造，逐步迁移，避免一次性重构的风险。
• 模型定义越详细，生成的OpenAPI文档越精准，同时还能自动帮你拦截不符合格式的请求，减少后端的校验代码。
• 两个工具都支持自定义Swagger UI的路径、标题、权限验证等配置，你可以查看工具的本地文档调整细节。

内容的提问来源于stack exchange，提问作者Akalanka Weerasooriya