Flask 3.x需用flask-openapi3生成OpenAPI文档，因其兼容ASGI、基于Pydantic v2，支持自动提取规范；须配置OPENAPI_VERSION、继承BaseModel、用@api装饰器并指定responses，路径参数与请求体需显式标注，模型变更须重启进程。
Flask 3.x 默认不带 OpenAPI 文档，得靠第三方库补上
Flask 3.x 完全移除了内置的 flask restful 和文档生成能力，flask-swagger-ui 这类老工具也不再兼容（会报 AttributeError: 'Flask' object has no attribute 'add_url_rule'）。必须用明确支持 ASGI、兼容 Flask 3.x 的方案——目前最稳的是 flask-openapi3，它基于 Pydantic v2，能自动从路由函数签名和模型中提取 OpenAPI 3.0.3 规范。
用 flask-openapi3 快速启动带 UI 的文档服务
安装后只需三步：定义模型、写路由、初始化扩展。注意别漏掉 app.config['OPENAPI_VERSION'] = '3.0.3'，否则 UI 加载会卡在 loading 状态。
pip install flask-openapi3- 定义请求/响应模型时，必须继承
pydantic.BaseModel（不是pydantic.v1.BaseModel），字段类型要明确（如id: int，不能只写id） - 路由函数必须加
@api.get()或@api.post()装饰器，并传入responses参数指定返回模型，否则字段不会出现在文档里 - 启动后访问
/openapi是 JSON Schema，/docs才是 Swagger UI 页面
from flask import Flask
from flask_openapi3 import OpenAPI, Info
info = Info(title='User API', version='1.0.0')
app = OpenAPI(__name__, info=info)
app.config['OPENAPI_VERSION'] = '3.0.3'
class UserQuery:
def __init__(self, name: str = None):
self.name = name
class UserResponse:
def __init__(self, id: int, name: str):
self.id = id
self.name = name
@app.get('/users')
def get_users(query: UserQuery):
return {'users': [{'id': 1, 'name': query.name or 'default'}]}
路径参数、请求体、查询参数混用时容易漏掉注解
Flask 3.x + flask-openapi3 不会自动推断参数位置，全靠类型提示和装饰器参数联动。比如路径参数必须显式写在 URL 模板里，且函数参数名要和 {id} 一致；请求体必须用 Body 包裹模型，否则会被当成查询参数解析。
- 路径参数：
@app.get('/users/{user_id}')→ 函数参数必须叫user_id: int - JSON 请求体：
from flask_openapi3 import Body; def create_user(body: Body[UserCreate]): - 表单数据：
body: Body[UserForm, dict] = Body(..., media_type='application/x-www-form-urlencoded') - 忽略
Body直接写body: UserCreate→ 文档里变成 query 参数，接口实际也收不到 JSON
调试文档不更新或字段缺失的常见原因
改了模型但 /docs 页面没变？大概率是 Python 缓存或模型未被 import 触发。OpenAPI spec 是应用启动时静态生成的，热重载不刷新 spec。
立即学习“Python免费学习笔记（深入）”；
- 确保所有用到的模型都在 app 启动前完成 import（比如放在
models.py并在app.py开头导入） - 修改模型字段后，必须重启 Flask 进程，
flask run --reload不保证重新生成 OpenAPI JSON - 如果字段类型是
Optional[str]，文档里会标为 nullable；但若写成str = None，会被当成必填字段（Pydantic v2 行为） - 嵌套模型要逐层定义，
address: Address中Address必须也是BaseModel子类，否则该字段直接消失
真正麻烦的是跨模块模型引用和循环导入——这时候文档生成会静默失败，页面空白，控制台却无报错。建议把所有 OpenAPI 相关模型收拢到一个 schemas.py 文件里统一管理。
