Connexion 3搭配Flask时中间件重复加载Swagger的问题求助

已创建openapi.yml文件并初始化Connexion应用，启动阶段无报错，但调用接口（如http://localhost:8080/api/v1/agent/1）时出现500错误，核心报错为：

ValueError: The name '/api/v1' is already registered for a different blueprint. Use 'name=' to provide a unique name.

日志显示Connexion在请求到来时重复尝试添加OpenAPI端点，触发蓝图重复注册冲突。

环境与代码信息 #

目录结构 #

/my_app
    /app
        __init__.py
        /api
            __init__.py
            api.py  # API端点实现
        /models
            __init__.py
            models.py  # SQLAlchemy模型
        swagger.yml  # OpenAPI规范
    .env
    config.py  # 配置文件
    main.py  # 应用入口

核心依赖 #

connexion[swagger-ui, uvicorn, flask]==3.0.5
Flask==3.0.1
Flask-SQLAlchemy==3.1.1
uvicorn==0.27.1

关键代码 #

app/init.py

def create_app(config_class=Config, **kwargs):
    
    load_dotenv()

    # 创建Connexion应用
    connex_app = connexion.FlaskApp(__name__, specification_dir='./')
    
    connex_app.add_api("swagger.yml") # 注释中包含base_path等未启用的配置

    application = connex_app.app

    # 加载配置
    application.config.from_object(config_class)
    application.config.update(kwargs)

    # 初始化数据库连接
    from app.models import init_app
    init_app(application)
    
    return connex_app

main.py

if __name__ == "__main__":
    app = create_app()
    app.run(host="0.0.0.0", port=8080)

这是Connexion 3.x版本在ASGI模式下的特定问题：

1. 启动阶段create_app中已经调用connex_app.add_api()完成了端点注册。
2. Connexion的MiddlewareMain类会在每个请求到来时重新构建中间件栈，而这个过程会再次调用add_api方法。
3. 由于未给API指定唯一name参数，Connexion默认使用OpenAPI配置中的base_path（即/api/v1）作为蓝图名称，重复注册时触发名称冲突。

有两种直接可行的修复方式：

方式1：给add_api指定唯一名称 #

修改app/__init__.py中的add_api调用，显式传入唯一的name参数，确保重复调用时蓝图名称不冲突：

connex_app.add_api(
    "swagger.yml",
    name="api_v1_unique"  # 任意唯一标识即可，比如业务相关名称
)

方式2：切换到WSGI模式运行 #

如果不需要ASGI特性，可指定使用WSGI服务器启动，避免中间件栈重复构建：
修改main.py：

if __name__ == "__main__":
    app = create_app()
    app.run(host="0.0.0.0", port=8080, server="flask")  # 用Flask内置WSGI服务器

或使用gunicorn启动：

gunicorn main:app.app

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