如何用OpenAPI Generator实现单后端多API版本兼容？

背景 #

网上缺少实用的OpenAPI规范版本控制落地指南，总结一套自动化实现方案能帮助众多开发者解决多版本API的后端部署问题。

API版本控制思路 #

核心目标：升级API时不强迫旧版客户端升级依赖包（如pip install --upgrade），具体规划：

• 后端与API客户端均通过OpenAPI Generator基于api_v1.yaml生成
• 版本迭代步骤：
  1. 复制api_v1.yaml得到api_v2.yaml
  2. 修改api_v2.yaml：将版本号设为2.0.0，服务器地址改为http://api.example.com/v2，同时完成不兼容的路由更新

问题 #

如何通过OpenAPI Generator生成单后端实例，同时支持v1和v2版本？要求：

• 后端可直接替代现有服务，http://api.example.com/v1提供v1业务逻辑，http://api.example.com/v2提供新功能
• 全程通过自动化脚本实现，禁止手动修改生成代码，适配CI/CD流程

实用实现方案 #

1. 规范文件的版本路径配置 #

确保两个规范文件的基础路径与版本绑定，且路径仅包含相对路由：

• v1规范的servers字段设为http://api.example.com/v1，paths下只写相对路径（如/users）
• v2规范的servers字段设为http://api.example.com/v2，paths同样使用相对路径
• 可用yq工具批量自动化修改规范文件，避免手动编辑：

  # 配置v1规范的基础路径
  yq eval '.servers[0].url = "http://api.example.com/v1"' api_v1.yaml -i
  # 配置v2规范的基础路径
  yq eval '.servers[0].url = "http://api.example.com/v2"' api_v2.yaml -i
  

2. 模块化生成路由模块 #

利用OpenAPI Generator的模块化特性，分别生成v1和v2的独立路由模块（以FastAPI为例）：

# 生成v1路由模块，指定输出目录和包名
openapi-generator generate -i api_v1.yaml -g python-fastapi -o ./generated/v1 --package-name api_v1
# 生成v2路由模块，指定输出目录和包名
openapi-generator generate -i api_v2.yaml -g python-fastapi -o ./generated/v2 --package-name api_v2

生成的模块包含独立的路由对象（如FastAPI的router），无需修改即可直接复用。

3. 编写统一主应用入口 #

手动编写一个极简的主入口文件（逻辑固定，无需频繁修改），将v1和v2路由挂载到对应前缀：

# main.py
from fastapi import FastAPI
from generated.v1.api.default_api import router as v1_router
from generated.v2.api.default_api import router as v2_router

app = FastAPI()

# 挂载v1路由到/v1前缀
app.include_router(v1_router, prefix="/v1")
# 挂载v2路由到/v2前缀
app.include_router(v2_router, prefix="/v2")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

这个文件仅做路由聚合，完全不修改生成的代码，符合自动化要求。

4. CI/CD自动化流程 #

在CI/CD脚本中串联以下步骤：

• 拉取最新的api_v1.yaml和api_v2.yaml
• 用yq自动配置规范文件的基础路径（若规范已预先配置可跳过）
• 运行OpenAPI Generator命令生成v1和v2路由模块
• 将主入口文件与生成的模块打包部署

关键注意事项 #

• 选择支持模块化路由的后端生成器：Python-FastAPI、Spring Boot、Node.js-Express等主流生成器均支持此模式
• 禁止在规范的paths中硬编码版本前缀，否则会出现路由重复（如/v1/v1/users）
• 若需共享业务逻辑（如数据库模型），可将共享代码抽离为独立包，通过OpenAPI Generator的modelPackage参数指定依赖路径，避免重复生成模型代码

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