Method for Automatic APIM Swagger Update Upon K8s Pod Deployment
개요
이 가이드는 백엔드 서비스가 Kubernetes 포드로 배포될 때마다 APIM 시스템에서 API의 Swagger (OpenAPI) 문서를 자동으로 업데이트하는 방법을 설명합니다. 이 프로세스는 CI/CD 파이프라인에서 유용하여 개발자 포털과 관리 콘솔이 항상 최신 API 사양을 반영하도록 보장합니다.
개념
Kubernetes 환경에서 Swagger 정의가 업데이트된 API가 재배포될 때, APIM 시스템은 문서를 자동으로 새로 고치지 않습니다. 이를 해결하기 위해 APIM에서 제공하는 내장 API를 사용하여 프로그래밍 방식으로 Swagger 업데이트를 트리거할 수 있습니다. 이를 통해 개발자 포털과 관리 콘솔 간의 문서 자동 동기화가 가능합니다.
할 수 있는 일
관리자 또는 DevOps 엔지니어로서 다음을 수행할 수 있습니다:
- APIM 콘솔에서 배포된 API의 api_id를 검색합니다.
- Swagger 업데이트를 트리거하기 위해 내부 APIM API를 호출합니다.
- 모든 포털에서 문서가 새로 고쳐졌는지 확인합니다.
단계 1: API 세부정보 확인 및 api_id 검색
문서 업데이트를 요청하려면 먼저 대상 API의 api_id가 필요합니다.
- 다음으로 이동합니다: APIM > API Management
- 업데이트할 API를 클릭하여 세부 정보 페이지를 엽니다.
- 빨간 테두리로 표시된 정보 아이콘을 클릭합니다.
이렇게 하면 API 메타데이터를 보여주는 팝업 창이 열리며, 여기에는 다음이 포함됩니다:
- project_id
- api_id
- gateway_id
단계 2: API 문서 업데이트 트리거
다음 curl 명령을 사용하여 Swagger 문서를 업데이트하는 APIM 내부 API를 호출합니다.
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" }'
### 필수 매개변수 \{#required-parameters}
| 매개변수 | 설명 |
| --- | --- |
| APIM Console K8s DNS | APIM 콘솔의 Kubernetes DNS 주소 |
| api_id | 1단계에서 검색한 API의 ID |
| x-apim-key | 내부 엔드포인트를 호출할 수 있는 권한이 있는 API 키 |
| description | (선택 사항) 업데이트 작업에 대한 메모 |
:::note
URL의 api_id 값을 이전에 검색한 올바른 값으로 바꾸는 것을 잊지 마세요. DNS 주소와 API 키에도 동일하게 적용됩니다.
:::
## 다음에 일어나는 일은? \{#what-happens-next?}
API 호출이 이루어지면:
- API의 Swagger 문서가 개발자 포털과 APIM 콘솔 모두에서 새로 고쳐집니다.
- 문서에 접근하는 사용자는 최신 버전을 보게 됩니다.
- 이는 CI/CD 파이프라인에 통합되어 매 배포 후 문서 유지 관리를 자동화할 수 있습니다.