如何在Azure DevOps中使用Swagger文件将API部署至APIM

不需要额外构建特殊的部署包，APIM原生支持直接导入标准Swagger/OpenAPI格式的定义文件，整个流程只需要做基础校验、调用Azure官方任务完成导入即可，具体步骤如下：

前置准备 #

• 确认仓库内存储的swagger.yaml符合OpenAPI 2.0/3.0规范，没有语法错误，所有本地引用的schema文件都已经同步提交到仓库对应路径
• 在Azure DevOps项目中配置好Azure RM类型的服务连接，给该连接对应的服务主体分配目标APIM实例的API Management Service Contributor角色，保证流水线有写入APIM的权限
• 提前确认外部API的后端服务地址、需要配置的API访问路径前缀、API版本信息

Pipeline核心配置 #

整个流水线不需要传统的编译打包环节，核心分两个步骤：

• Swagger文件格式校验
  提前拦截格式错误的配置文件，避免无效部署，示例步骤代码：

  trigger:
    - main # 配置触发流水线的分支
  
  pool:
    vmImage: ubuntu-latest
  
  steps:
  - task: CmdLine@2
    displayName: 校验Swagger文件合法性
    inputs:
      script: |
        npm install -g @apidevtools/swagger-cli
        swagger-cli validate $(Build.SourcesDirectory)/path/to/your/swagger.yaml
  

  注意：请把路径替换成你仓库里swagger.yaml的实际存放路径

• 导入API到APIM
  直接用Azure官方提供的APIM部署任务完成导入，不需要手写复杂的REST API调用，示例配置：

  - task: AzureApiManagement@3
    displayName: 同步Swagger定义到APIM
    inputs:
      azureSubscription: '你配置好的Azure服务连接名称'
      ResourceGroupName: 'APIM实例所在的资源组名称'
      InstanceName: '你的APIM实例名称'
      ApiId: '自定义API唯一标识，比如third-party-pay-api'
      ApiPath: 'API访问路径前缀，比如api/pay/v1'
      OpenApiSpecPath: '$(Build.SourcesDirectory)/path/to/your/swagger.yaml'
      ServiceUrl: '外部API的实际后端服务根地址'
      Protocols: 'https'
      IsCurrent: true
  

  注意：如果找不到这个任务，直接在Azure DevOps的任务市场搜索安装官方的Azure API Management扩展即可

可选扩展配置 #

• 如果需要给API配置JWT校验、限流、CORS、请求转发等策略，可以在导入步骤后新增步骤，读取仓库内提前写好的APIM策略XML文件，同步上传到APIM对应API/操作级别即可
• 如果需要做API多版本管理，只需要在任务参数中配置对应的版本集ID，每次更新不同版本的swagger文件就可以自动完成多版本API的同步
• 如果需要区分开发、测试、生产多环境部署，只需要把APIM实例名、后端服务地址这些参数换成流水线变量，按不同环境赋值即可

常见踩坑点 #

• 不需要特意构建所谓"可推送至Azure Portal的版本"：APIM可以直接识别标准格式的swagger yaml文件，整个流程没有编译打包的要求
• 如果swagger文件里用了$ref引用其他本地schema文件，一定要保证引用路径是相对路径且所有被引用文件都在仓库内，不然导入时会报解析错误
• 部署报403权限错误时，直接去APIM实例的访问控制(IAM)页面，检查服务连接对应的服务主体是否已经分配了正确的贡献者权限

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