api-gateway-openapi-spec-authoring

Write, migrate, and validate OpenAPI specifications for Google Cloud API Gateway.

23.7k|2.0k|Updated Mar 31, 2026
Ready to run
npx skills add https://github.com/google/skills --skill api-gateway-openapi-spec-authoring-google
💬 Prompt for ChatGPT / Claude Chat▼
Please help me install this Agent Skill.
Skill: api-gateway-openapi-spec-authoring
Source: https://github.com/google/skills/tree/main/skills/cloud/api-gateway-openapi-spec-authoring
Command: npx skills add https://github.com/google/skills --skill api-gateway-openapi-spec-authoring-google

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires PyYAML, and includes scripts (resource) and references (resource) components.

What problem does it solve? Migrating OpenAPI 2.0 specs to 3.x, writing new OpenAPI 3.x specs, and fixing API config creation failures are error-prone manual tasks. This Skill automates the conversion process, applies the correct Google extensions, and validates against API Gateway rules before deployment. ## Core Features & Use Cases - OpenAPI 2.0 to 3.x Migration: Automatically converts standard fields and restructures Google extensions (x-google-backend, x-google-management, x-google-auth) into their OpenAPI 3.x forms. - Spec Validation: Runs deterministic checks before deployment to catch unsupported patterns like inline backend objects, improper path parameter translation, and quota configuration errors. - API Config Error Resolution: Matches error messages from failed gcloud api-gateway api-configs create commands to specific fixes and explains what changed in the spec. - Use Case: You have an OpenAPI 2.0 spec for a Cloud Run backend with JWT authentication and quota limits. Use this Skill to migrate it to OpenAPI 3.x, apply the correct extension structure, validate with the Python script, and generate a deployment-ready spec. ## Quick Start Provide your current OpenAPI spec file or the API ID of an active gateway, and request the Skill to either migrate it from OpenAPI 2.0 to 3.x or fix a specific API config creation error.

Frequently Asked Questions about api-gateway-openapi-spec-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate an OpenAPI 2.0 spec to OpenAPI 3.x for API Gateway?▼

Convert standard fields (swagger to openapi, securityDefinitions to components.securitySchemes, definitions to components.schemas), then move each Google extension using the Extension Mapping Table: inline x-google-backend objects become named backends in x-google-api-management, JWT settings nest in x-google-auth, and metrics move from lists to maps. Add x-google-endpoint: {} to the servers entry with your base path.

What does pathTranslation do in API Gateway backends?▼

APPEND_PATH_TO_ADDRESS sends the full request path with the base path to the backend (use for Cloud Run services that route by path). CONSTANT_ADDRESS sends every request to the fixed address unchanged and converts path parameters to query parameters (use for Cloud Functions serving a single operation). Always set pathTranslation explicitly on every backend.

Why does my API config fail with 'extension is only supported in OpenAPI 2.x'?▼

Your spec contains OpenAPI 2.0 extensions in an OpenAPI 3.x format. The most common causes are inline x-google-backend objects (move to x-google-api-management.backends), x-google-management at the root (move metrics and limits to x-google-api-management), and x-google-issuer on a security scheme (nest in x-google-auth). Run the validator script to identify all occurrences.

How do I set up quotas that actually enforce in API Gateway?▼

Define metrics in x-google-api-management.metrics and limits in x-google-api-management.quota.limits with the same metric name, set x-google-quota on each operation (not at root or path level), and require an API key in every security alternative of that operation. API Gateway uses the API key to identify the consumer project for quota counting.

Can I use two JWT schemes in one security requirement?▼

No. API Gateway rejects AND-ing two oauth2 schemes in one requirement object. Use an OR instead by putting each JWT scheme in its own requirement object: security: [{firebase: []}, {google_id_token: []}] works, but [{firebase: [], google_id_token: []}] fails.

What does the validator script check and what does it miss?▼

The script validates API Gateway-specific rules: extension structure, backend configuration, path translation, security combinations, quota setup, and schema type lists. It does NOT check general OpenAPI validity (like $ref targets that exist), required parameters, parameter types, or request body schemas. A PASS means the script found no API Gateway issues, but gcloud api-configs create is the final validation.