如何在Azure APIM与Functions中实现无重复版本号的URL式API版本控制

核心需求 #

• 通过URL模式实现API版本控制（例如v1/resource、v2/resource）
• 提供可查阅的Swagger UI（集成在APIM开发者门户）
• 全流程CI/CD自动化

现有技术栈与流程 #

REST API基于Azure API Management（APIM）与Azure Functions构建，CI/CD流程为：

1. 借助azure functions openapi extension导出OpenAPI Spec文档
2. 通过Terraform将Spec导入APIM作为新的API版本

当前问题 #

Azure Function的HttpTrigger必须指定唯一路由，示例代码：

[HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "v1/creative-fields")]
[HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "v2/creative-fields")]

在APIM中配置URL式版本集后，设置v1路径为baseurl/v1、v2为baseurl/v2，最终显示的URL变成baseurl/v2/v2/creative-fields，出现版本号重复的问题。

已尝试的无效方案 #

1. 弃用APIM版本控制：导致APIM开发者门户的Swagger端点全部混在一起，无法按版本区分
2. 更换OpenAPI Spec生成流程（原方案为英文，需汉化）：未解决核心的URL重复问题

可行解决方案 #

方案1：调整Azure Functions路由，移除版本前缀 #

将Function的路由改为不带版本号的通用路径，示例：

[HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "creative-fields")]

通过APIM版本集的URL策略添加版本前缀，APIM会自动将baseurl/v1/creative-fields路由到对应的Function版本。

优势：

• 彻底避免URL重复，符合预期的版本控制路径
• APIM开发者门户的Swagger会按版本集自动分组展示
• 无需修改OpenAPI生成流程，CI/CD可沿用现有逻辑

注意事项：

• 不同版本的Function需设置不同函数名或部署到不同Function App实例，确保路由唯一（比如函数名设为v1-creative-fields和v2-creative-fields，路由统一用creative-fields）
• Terraform导入OpenAPI Spec时，需指定对应的版本集和版本号，确保APIM正确关联

方案2：修改OpenAPI Spec，移除路径中的版本前缀 #

在CI/CD流程中，导出OpenAPI Spec后，通过脚本批量替换路径中的版本前缀，再导入APIM。

示例Python脚本逻辑：

import json

with open('openapi.json', 'r') as f:
    spec = json.load(f)

# 移除路径中的v1/v2前缀
new_paths = {}
for path in spec['paths']:
    if path.startswith('/v1/'):
        new_path = path.replace('/v1/', '/', 1)
        new_paths[new_path] = spec['paths'][path]
    elif path.startswith('/v2/'):
        new_path = path.replace('/v2/', '/', 1)
        new_paths[new_path] = spec['paths'][path]

spec['paths'] = new_paths

with open('openapi-cleaned.json', 'w') as f:
    json.dump(spec, f, indent=2)

用清理后的Spec导入APIM版本集，即可避免URL重复。

优势：

• 无需修改Azure Functions的路由配置
• 保留APIM版本集的分组能力，Swagger UI正常按版本展示

注意事项：

• 需确保脚本能正确处理所有路径，避免遗漏或错误替换
• CI/CD流程中需新增Spec清理步骤，维护成本略高

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