Method for Automatic APIM Swagger Update Upon K8s Pod Deployment
概述
本指南解释了如何在后端服务作为 Kubernetes pod 部署时，自动更新 APIM 系统中 API 的 Swagger (OpenAPI) 文档。此过程在 CI/CD 管道中非常有用，以确保开发者门户和管理控制台始终反映最新的 API 规范。
概念
当 API 在 Kubernetes 环境中重新部署并更新 Swagger 定义时，APIM 系统不会自动刷新文档。为了解决这个问题，您可以使用 APIM 提供的内置 API 以编程方式触发 Swagger 更新。这允许在开发者门户和管理控制台之间自动同步文档。
您可以做什么
作为管理员或 DevOps 工程师，您可以：
- 从 APIM 控制台检索已部署 API 的 api_id
- 调用内部 APIM API 以触发 Swagger 更新
- 确认文档在所有门户中已刷新
步骤 1：检查 API 详细信息并检索 api_id
要请求文档更新，您首先需要目标 API 的 api_id。
- 导航到：APIM > API 管理
- 点击您想要更新的 API 以打开其详细信息页面。
- 点击红色轮廓显示的 Info 图标。
这将打开一个弹出窗口，显示 API 元数据，包括：
- project_id
- api_id
- gateway_id
步骤 2：触发 API 文档更新
使用以下 curl 命令调用更新 Swagger 文档的 APIM 内部 API。
```markdown
curl -X 'POST' 'https://`<APIM Console K8s DNS>`/apim/org/default/spc/all/restApi/deployV2?api_id=`<your-api-id>`&swagger_latest_update=true' \
-H 'accept: application/json' \
-H 'x-apim-key: `<your-apim-key>`' \
-H 'Content-Type: application/json' \
-d '`{ "description": "APIM REST API - API Swagger Update" }`'
必需参数
| 参数 | 描述 |
|---|---|
| APIM Console K8s DNS | 您的 APIM 控制台的 Kubernetes DNS 地址 |
| api_id | 在步骤 1 中检索到的 API 的 ID |
| x-apim-key | 具有调用内部端点权限的 API 密钥 |
| description | （可选）更新操作的备注 |
备注
请确保在 URL 中用之前检索到的正确值替换 api_id 值。DNS 地址和 API 密钥同样适用。
接下来会发生什么？
一旦 API 调用被发出：
- API 的 Swagger 文档将在开发者门户和 APIM 控制台中刷新
- 访问文档的用户将看到最新版本
- 这可以纳入您的 CI/CD 管道，以在每次部署后自动维护文档