Skip to main content

Method for Automatic APIM Swagger Update Upon K8s Pod Deployment

Overview​

This guide explains how to automatically update the Swagger (OpenAPI) documentation of your API in the APIM system whenever the backend service is deployed as a Kubernetes pod. This process is useful in CI/CD pipelines to ensure that both the Developer Portal and Admin Console always reflect the most up-to-date API specifications.

Concept​

When an API is redeployed with updated Swagger definitions in a Kubernetes environment, the APIM system does not automatically refresh the documentation. To solve this, you can programmatically trigger a Swagger update using a built-in API provided by APIM. This allows automated synchronization of documentation across both the Developer Portal and the Admin Console.

What You Can Do​

As an administrator or DevOps engineer, you can:

  • Retrieve the api_id of the deployed API from the APIM console
  • Call an internal APIM API to trigger the Swagger update
  • Confirm the documentation is refreshed across all portals

Step 1: Check API Details and Retrieve api_id​

To request a documentation update, you first need the api_id of the target API.

  1. Navigate to: APIM > API Management
  2. Click on the API you want to update to open its detail page.
  3. Click the Info icon shown with a red outline.

This will open a pop-up window showing the API metadata, including:

  • project_id
  • api_id
  • gateway_id

Step 2: Trigger API Document Update​

Use the following curl command to call the APIM internal API that updates the Swagger document.

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​

ParameterDescription
APIM Console K8s DNSThe Kubernetes DNS address of your APIM console
api_idThe ID of the API retrieved in Step 1
x-apim-keyAPI key with permission to call the internal endpoint
description(Optional) A note for the update operation
note

Be sure to replace the api_id value in the URL with the correct value retrieved earlier. The same applies to the DNS address and API key.

What Happens Next?​

Once the API call is made:

  • The Swagger document of the API will be refreshed in both the Developer Portal and APIM Console
  • Users accessing the documentation will see the latest version
  • This can be incorporated into your CI/CD pipeline to automate documentation maintenance after every deployment