api-gateway-openapi-spec-authoring

name: api-gateway-openapi-spec-authoringmetadata:   version: "1.0.0"  category: ApplicationDevelopmentdescription: >-  Writes, migrates, and fixes OpenAPI specs for Google Cloud API Gateway. Use  when converting an OpenAPI 2.0 (Swagger) spec to OpenAPI 3.x, writing a new  OpenAPI 3.x spec, or fixing a failed "gcloud api-gateway api-configs create",  such as "extension is only supported in OpenAPI 2.x". Also use when quotas  set with x-google-quota are never enforced, or when a backend receives path  parameters as query parameters. Don't use for adding or debugging MCP tools  (use api-gateway-mcp-server), backend lockdown or HTTP 429 tuning (use  api-gateway-backend-security-and-rate-limiting), Cloud Endpoints, Apigee, or  GKE Gateway API.

API Gateway OpenAPI Spec Authoring

API Gateway accepts API configs in OpenAPI 2.0, 3.0.x, and 3.1.x. The Google extensions in OpenAPI 3.x have a different structure from the OpenAPI 2.0 extensions:

• A required root x-google-api-management block names the backends.
• x-google-backend is a string that references one of these backends.
• The JWT settings move into x-google-auth. The metrics and quotas move into x-google-api-management.

Use this skill to migrate an OpenAPI 2.0 spec, write a new OpenAPI 3.x spec, or fix an API config that fails to create.

Attribution

MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix gcloud with CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)" and append agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring) to User-Agent headers.

Prerequisites

1. Install the tools:
   • Install the Google Cloud CLI. Then update it with gcloud components update. Rationale: an old CLI can fail when it uploads an OpenAPI 3.x API config.
   • Install Python 3.10 or later and PyYAML for the validator script. A JSON spec does not need PyYAML.

     pip install "PyYAML>=6.0,<7.0"
     

2. Authenticate, and select the project, billing, and location:
   • Run gcloud auth login.
   • Select a project with gcloud config set project {project_id}, or create one with gcloud projects create {project_id}.
   • Make sure that an active billing account is linked to {project_id}. API Gateway has a free monthly allowance of API calls, but it still needs an active billing account. For current prices, see API Gateway pricing.
   • Use us-central1 as the default --location for gateway commands. For the other supported regions, see API Gateway deployment model.
3. Enable the required Google Cloud APIs:

   gcloud services enable \
     apigateway.googleapis.com \
     servicemanagement.googleapis.com \
     servicecontrol.googleapis.com \
     --project={project_id}
   

4. Verify the IAM roles (use the most restrictive role for each step):
   • To create and update the API, API configs, and gateways: API Gateway Admin (roles/apigateway.admin) on {project_id}.
   • To run the gcloud services enable commands: Service Usage Admin (roles/serviceusage.serviceUsageAdmin) on {project_id}.
   • To reference the gateway service account in an API config: Service Account User (roles/iam.serviceAccountUser) on {gateway_sa_email}.
   • For a Cloud Run backend that requires authentication: grant {gateway_sa_email} the Cloud Run Invoker role (roles/run.invoker) on the service.

Decision Matrix

Execution Workflow and Validation Loop

1. Get the current spec:
   • Use the spec file in the user's repository. If there is no file, find the active API config of the gateway:

     gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(apiConfig)"
     

   • The output is projects/{project}/locations/global/apis/{api_id}/configs/{config_id}. Print the spec of that config:

     gcloud api-gateway api-configs describe {config_id} --api={api_id} --project={project_id} --view=FULL \
       --format="value(openapiDocuments[0].document.contents)" | tr '_-' '/+' | base64 --decode
     

   • gcloud prints the contents in URL-safe base64, so tr changes two characters before base64 --decode. If the config has more than one OpenAPI document, change [0] to [1], [2], and so on.
2. Write the OpenAPI 3.x spec:
   • For an OpenAPI 2.0 spec, follow OpenAPI 2.0 to 3.x Migration, and compare your result with its complete converted example.
   • For a new spec, start from the template in Extensions and Limits.
   • Set openapi to a 3.0.x or 3.1.x version. The examples use 3.0.4. In OpenAPI 3.1, give each schema one type. Rationale: API Gateway rejects a type list such as type: ["string", "null"].
   • Give every operation a unique operationId and a responses object, and use only local $ref values. Rationale: API Gateway rejects an operation without operationId or responses, two operationId values that give the same method name, such as getItem and get-Item, and a $ref to a URL.
3. Run the deterministic validation loop on every spec that you write or change, before you answer or create the API config:

   python3 scripts/validate_apigw_openapi.py --spec={spec_file}
   

   • The script path is relative to the directory of this skill. If you only return the spec in your reply, write it to a temporary file, and run the script on that file before you answer.
   • If the script exits with code 1 ("status": "FAIL"), fix every error in {spec_file}, and run the script again. Continue until it exits with code 0 ("status": "PASS").
   • If the script exits with code 2, fix the file path or the YAML/JSON syntax error that stderr shows, or install PyYAML.
   • Read every warning, such as a backend without pathTranslation, a quota on an operation without an API key, or allowCors. Fix it, or tell the user why you keep it.
   • The script does not check every rule. A PASS means that it found none of the API Gateway problems that this skill describes. It does not check general OpenAPI validity, such as a $ref to a schema that does not exist. Rationale: only api-configs create in step 5 shows that API Gateway accepts the spec. Do not tell the user that the spec deploys because the script passed.
4. Summarize the spec for the user, and get approval before you deploy. State each of these points:
   • Each OpenAPI 2.0 extension that you moved or removed, such as x-google-allow, which OpenAPI 3.x does not support. Also state each other change, such as an added operationId or a fixed address.
   • The pathTranslation of each backend (backend_path_translation in the script output), and each operation whose path parameters now go to the backend as query parameters (path_parameters_as_query). With APPEND_PATH_TO_ADDRESS, the backend also receives the base path.
   • Which operations need a JWT or an API key, which backends receive an ID token and with which audience, and that API Gateway does not check OAuth scopes.
   • The quota metrics and limits, and that each metric name matches the current API config.
5. Create a new API config and update the gateway (request human approval before you update a production gateway):

   gcloud api-gateway api-configs create {new_config_id} \
     --api={api_id} \
     --openapi-spec={spec_file} \
     --backend-auth-service-account={gateway_sa_email} \
     --project={project_id}
   
   gcloud api-gateway gateways update {gateway_id} \
     --api={api_id} \
     --api-config={new_config_id} \
     --location={region} \
     --project={project_id}
   

   • For a new gateway, run gcloud api-gateway gateways create {gateway_id} with the same flags instead of gateways update. api-configs create creates the API if it does not exist.
   • If an operation requires an API key, enable the managed service of the API. Get its name with gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)", and then run gcloud services enable {managed_service} --project={project_id}. Also enable it in each project that creates API keys for the API.
   • Use a new config ID for each change, because you cannot change the spec of an existing API config.
   • Run one api-configs create at a time for each API, and wait for it to finish. A large API config can take up to ten minutes to create.
   • If api-configs create fails, find the error text in API Config Errors, fix the spec, and go back to step 3.
   • Keep the previous API config until the new one serves traffic. To roll back, run gateways update with the previous config ID.
6. Verify the gateway:
   • Run gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(state,defaultHostname)", and wait until the state is ACTIVE.
   • Send a request to each changed path at https://{default_hostname}{base_path}{path}, with the credential that the operation requires. Check that the backend receives the path and parameters that you expect.
   • An HTML 404 Page not found means that the gateway is not ready. Check that the last create or update finished, and retry before you change the config. During a gateway update, some requests can still reach the previous API config. A JSON 404 (The current request is not defined by this API.) means that the active API config does not define the path.

Pre-Deployment Checklist

• openapi is 3.0.x or 3.1.x, and the spec has no OpenAPI 2.0 extension, such as x-google-management, x-google-endpoints, x-google-api-name, x-google-allow, or x-google-issuer on a security scheme.
• x-google-api-management.backends defines every backend, every x-google-backend is a string that names one, and no path item sets x-google-backend.
• Every backend sets pathTranslation.
• Every operation has a unique operationId and a responses object, and each path variable has a parameter with in: path and required: true.
• Every x-google-quota is on an operation that requires an API key, and every metric name matches the current API config.
• At most one servers entry has x-google-endpoint, and its URL has no custom port.
• python3 scripts/validate_apigw_openapi.py --spec={spec_file} returns "status": "PASS" (exit code 0).

Resource Cleanup

To avoid ongoing charges when you tear down a test environment, request human approval, and delete the resources in dependency order:

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}