An OpenAPI gateway spec you never edit by hand
Per-service path fragments, a small Node generator that enforces the rules humans forget, and a CI check that keeps the API Gateway config honest.
Two mistakes in a hand-edited gateway spec never fail a deploy. Someone copies an operation block and drops its security section, so the route stops validating tokens and the service behind it sees an anonymous caller. Someone else adds a backend override to a single operation, and the gateway quietly changes how it builds the upstream URL, so /users/{userId} reaches the service as /?userId=42. Both configs upload cleanly. Both surface later as user-facing bugs in code nobody touched.
Both mistakes are the same kind of mistake: a rule that lives in people's heads, applied to a file that people edit. The remedy is to stop treating the gateway spec as a source file. Humans write small per-service fragments that say nothing about the gateway. A generator of about a hundred lines merges them, injects every piece of gateway plumbing, and refuses to write output when a fragment breaks a rule. The merged spec is committed, CI fails if it is stale, and the deploy job is the only thing that turns it into a gateway config. The rest of this article builds that, one piece at a time.
I got here the slow way. My own gateway spec ran to about four thousand lines of JSON, and adding a route meant scrolling to the right place and pasting a path block. It worked with ten routes and stopped working surprisingly fast after that. Edits near each other conflicted constantly, copy-paste carried over a stale backend address and, once, a response schema borrowed from the wrong endpoint, and reviewers skimmed the diffs because every block of that file looks like every other.
What API Gateway does with a spec, and why that matters here#
API Gateway has three resources. An API is a named container. An API config is an uploaded spec attached to that API, and it is immutable: apart from labels and display name, you cannot modify one after creating it. A gateway is a regional deployment of the managed Envoy-based proxy (ESPv2) that serves exactly one config at a time. Shipping a route change therefore always means creating a new config and pointing the gateway at it. That shape is what makes a generated, committed spec a good fit: every deploy is already "take this file, make a new immutable thing from it".
The product originally took only OpenAPI 2.0 (Swagger). The release notes show OpenAPI 3.0 support added in November 2025, with its own extension layout. This article emits 2.0, because that is what most existing gateways run and because the fragment-and-generator idea does not care which version comes out. If you start fresh on 3.0, only the generator's output stage changes.
Google-specific behaviour lives in vendor extensions. Two matter here: x-google-backend says where an operation is forwarded, and securityDefinitions entries carrying x-google-issuer, x-google-jwks_uri and x-google-audiences say how to validate tokens.
Why not simply split the file? Passing several files to --openapi-spec still leaves each one repeating the host, extensions and security definitions, and nothing checks rules across files. Generating from each service's own schema (Fastify, NestJS decorators) is attractive if every service already publishes one, but it couples the gateway to every service's build and mixes route metadata with gateway metadata. Terraform's templatefile keeps the spec next to the gateway resource, but routes change daily and infrastructure should not. The generator wins on one point: the rule "every operation declares its security explicitly" stops being a line in a review checklist and becomes code that runs on every commit.
Write fragments that say nothing about the gateway#
The layout is a gateway/ directory with four parts. paths/<service>/*.json holds fragments. envs/<env>.json holds per-environment data. scripts/generate-spec.mjs merges and validates. dist/openapi.<env>.json is the committed output, so reviewers see the effective diff and a deploy is reproducible from a commit alone.
A fragment is deliberately boring. It names its service and lists plain path items. No backend URL, no issuer, nothing environment-specific:
{
"service": "users",
"paths": {
"/v1/users/{userId}": {
"get": {
"operationId": "getUser",
"security": [{ "firebase": [] }],
"parameters": [
{ "name": "userId", "in": "path", "required": true, "type": "string" }
],
"responses": { "200": { "description": "The user profile" } }
}
},
"/v1/public/users/{userId}/card": {
"get": {
"operationId": "getPublicUserCard",
"security": [],
"parameters": [
{ "name": "userId", "in": "path", "required": true, "type": "string" }
],
"responses": { "200": { "description": "Public card, no auth" } }
}
}
}
}Note "security": [] on the public route. In OpenAPI 2.0 an empty array means "no authentication", while omitting the key means "inherit the top-level default". The generator forbids omission, so every operation states its intent.
That rule exists because of a bug that cost me more time than any other in this setup. I had a public endpoint that also personalised its response when a logged-in user called it, and the service branched on the forwarded user header. The route's fragment, being public, had no security definition at all, so the gateway never processed auth for it: valid tokens arrived and were ignored, and the backend saw every caller as anonymous. A later variant went the other way, with an endpoint that required user context returning 401 to users who were correctly signed in. Every component was behaving correctly. The token was valid, the gateway followed its spec and the service reported a missing header, so the defect was four lines of JSON that were not there, and absences do not show up in logs. Public routes that personalise now carry the security definition with the anonymous path allowed, and the fragment template and generator force an explicit decision for every route.
Keep what differs between environments in one small file#
Staging and production should differ only in data: the managed hostname, the Firebase project, and a map from service names to Cloud Run URLs.
{
"host": "public-api-0a1b2c3d4e5f6.apigateway.my-app-staging.cloud.goog",
"firebaseProject": "my-app-staging",
"backends": {
"users": "https://users-api-abc123-ew.a.run.app",
"media": "https://media-api-abc123-ew.a.run.app"
}
}The host value is the API's managed service name, which gcloud api-gateway apis describe API_ID prints in its managedService field. It matters for CORS, as the traps section shows.
Generate the spec, and refuse to when a rule is broken#
This is the whole generator. It runs on Node 22 with no dependencies:
import { readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from "node:fs";
import { dirname, join, relative } from "node:path";
import { fileURLToPath } from "node:url";
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const ENVS = ["staging", "prod"];
const METHODS = new Set(["get", "put", "post", "delete", "options", "head", "patch"]);
function readJson(file) {
try {
return JSON.parse(readFileSync(file, "utf8"));
} catch (err) {
throw new Error(`${relative(root, file)}: ${err.message}`);
}
}
function* jsonFiles(dir) {
for (const name of readdirSync(dir).sort()) {
const p = join(dir, name);
if (statSync(p).isDirectory()) yield* jsonFiles(p);
else if (name.endsWith(".json")) yield p;
}
}
function build(envName) {
const env = readJson(join(root, "envs", `${envName}.json`));
const errors = [];
const paths = {};
const opIds = new Map();
for (const file of jsonFiles(join(root, "paths"))) {
const where = relative(root, file);
const frag = readJson(file);
const address = env.backends[frag.service];
if (!address) {
errors.push(`${where}: service "${frag.service}" has no backend in envs/${envName}.json`);
continue;
}
for (const [path, item] of Object.entries(frag.paths ?? {})) {
const label = (m) => `${where}: ${m.toUpperCase()} ${path}`;
if (/[^/]\{|\}[^/]/.test(path)) errors.push(`${where}: ${path} uses a partial-segment template`);
const templated = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
paths[path] ??= {};
for (const [method, op] of Object.entries(item)) {
if (!METHODS.has(method)) { errors.push(`${where}: ${path} has unknown key "${method}"`); continue; }
if (paths[path][method]) errors.push(`${label(method)} is defined twice`);
if (!Array.isArray(op.security)) errors.push(`${label(method)} must declare security ([] for public)`);
if (op["x-google-backend"]) errors.push(`${label(method)} sets x-google-backend by hand`);
if (!op.operationId) errors.push(`${label(method)} has no operationId`);
else if (opIds.has(op.operationId)) errors.push(`${label(method)} reuses operationId from ${opIds.get(op.operationId)}`);
else opIds.set(op.operationId, where);
const declared = new Set((op.parameters ?? []).filter((p) => p.in === "path").map((p) => p.name));
for (const name of templated) {
if (!declared.has(name)) errors.push(`${label(method)} does not declare path parameter "${name}"`);
}
paths[path][method] = {
...op,
"x-google-backend": { address, path_translation: "APPEND_PATH_TO_ADDRESS" },
};
}
}
}
if (errors.length) throw new Error(`Spec for ${envName} is invalid:\n ${errors.join("\n ")}`);
return {
swagger: "2.0",
info: {
title: "public-api",
version: "1.0.0",
description: "GENERATED by gateway/scripts/generate-spec.mjs. Edit gateway/paths/ instead.",
},
host: env.host,
"x-google-endpoints": [{ name: env.host, allowCors: true }],
schemes: ["https"],
produces: ["application/json"],
securityDefinitions: {
firebase: {
authorizationUrl: "",
flow: "implicit",
type: "oauth2",
"x-google-issuer": `https://securetoken.google.com/${env.firebaseProject}`,
"x-google-jwks_uri":
"https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com",
"x-google-audiences": env.firebaseProject,
},
},
paths: Object.fromEntries(Object.keys(paths).sort().map((p) => [p, paths[p]])),
};
}
const check = process.argv.includes("--check");
let stale = false;
for (const envName of ENVS) {
const out = join(root, "dist", `openapi.${envName}.json`);
const next = `${JSON.stringify(build(envName), null, 2)}\n`;
if (check) {
let current = "";
try { current = readFileSync(out, "utf8"); } catch { /* missing counts as stale */ }
if (current !== next) {
console.error(`${relative(root, out)} is stale. Run: node gateway/scripts/generate-spec.mjs`);
stale = true;
}
} else {
mkdirSync(dirname(out), { recursive: true });
writeFileSync(out, next);
}
}
if (stale) process.exit(1);A few choices in there deserve an explanation.
path_translation is always explicit. The extension reference says that when x-google-backend sits at the top level, path_translation defaults to APPEND_PATH_TO_ADDRESS, and when it sits on an operation it defaults to CONSTANT_ADDRESS. With a constant address, the request goes to exactly the configured URL and path parameters become query parameters: a request for /hello/world against the template /hello/{name} arrives as ?name=world. A Cloud Run service that routes on /v1/users/:userId then returns 404 for every call. Because the generator puts the backend on each operation (one spec, many services), it must set APPEND_PATH_TO_ADDRESS every time. Setting it once, in code, means nobody can forget it in a fragment. If a service is hit on its root path with unexpected query strings, check this first.
Security definitions come from the environment. The Firebase block matches the one in the Firebase authentication guide; only the project ID changes between environments. The same shape works for any OIDC issuer with a JWKS endpoint.
Partial path segments are rejected. The OpenAPI 3 limitations page says API Gateway rejects parameters that correspond to partial segments, such as /items/prefix_{id}_suffix. The generator applies the same rule to every spec, so a template like /files/{name}.json fails in CI instead of at upload.
Output is deterministic. Files are read in sorted order and paths are sorted before writing, so the same inputs always give byte-identical output. That is what makes the --check comparison meaningful. On Windows, add gateway/dist/*.json text eol=lf to .gitattributes, or a checkout with automatic CRLF conversion will look stale forever.
Errors are collected, not thrown one at a time. A developer who breaks three rules gets three lines, not three round trips.
Let services trust the gateway, and only the gateway#
Behind the gateway, a service should not verify the token again. When x-google-backend sets an address, the gateway overrides the original Authorization header with its own ID token for the backend and moves the client's value to X-Forwarded-Authorization. The validated result arrives in X-Apigateway-Api-Userinfo, a base64url-encoded copy of the JWT payload:
import type { FastifyRequest } from "fastify";
export interface GatewayUser {
sub: string;
email?: string;
}
export function gatewayUser(req: FastifyRequest): GatewayUser | null {
const raw = req.headers["x-apigateway-api-userinfo"];
if (typeof raw !== "string" || raw === "") return null;
const claims = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
return typeof claims.sub === "string" ? { sub: claims.sub, email: claims.email } : null;
}Trusting this header is only safe if nothing except the gateway can reach the service. Deploy each Cloud Run service with authentication required and grant roles/run.invoker to the gateway's service account alone. Otherwise anyone who discovers the run.app URL can send a forged header. The least-privilege article covers how to structure those service accounts.
The gateway calls backends as the service account you pass when creating the config, so create one and give it invoker on each service it fronts:
gcloud iam service-accounts create gateway-invoker --project=my-app-staging
for svc in users-api media-api; do
gcloud run services add-iam-policy-binding "$svc" \
--region=europe-west1 --project=my-app-staging \
--member="serviceAccount:gateway-invoker@my-app-staging.iam.gserviceaccount.com" \
--role="roles/run.invoker"
doneThe ID token the gateway mints uses the backend address as its audience by default, which is what Cloud Run expects. You only need jwt_audience when the address and the expected audience differ, for example when the address is a custom domain in front of the service.
Make CI prove the committed spec is current#
One step, on every pull request that touches gateway/:
name: gateway
on:
pull_request:
paths: ["gateway/**"]
jobs:
spec-up-to-date:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- run: node gateway/scripts/generate-spec.mjs --checkA fragment that breaks a rule fails here with a readable message. A fragment that is valid but whose output was not regenerated also fails, which forces the effective spec diff into the pull request where a reviewer can see it. The spec has since grown past 300 routes, and a route change is still a fragment diff of about twenty lines that a reviewer can hold in their head. Nobody resolves merge conflicts in generated output; they regenerate it. Writing the build script took me an afternoon, and I count it among the best trades I have made on this project.
Ship each spec as a new config#
Because configs are immutable, each deploy creates one with a unique ID and then points the gateway at it. Config IDs allow 63 lowercase letters, digits and dashes, so a timestamp plus a short commit SHA fits:
#!/usr/bin/env bash
set -euo pipefail
ENV="${1:?usage: deploy.sh staging|prod}"
PROJECT="my-app-${ENV}"
CONFIG_ID="cfg-$(date -u +%Y%m%d-%H%M%S)-${GITHUB_SHA:0:7}"
gcloud api-gateway api-configs create "$CONFIG_ID" \
--api=public-api --project="$PROJECT" \
--openapi-spec="gateway/dist/openapi.${ENV}.json" \
--backend-auth-service-account="gateway-invoker@${PROJECT}.iam.gserviceaccount.com"
gcloud api-gateway gateways update public-gw \
--api=public-api --api-config="$CONFIG_ID" \
--location=europe-west1 --project="$PROJECT"The deploy job authenticates with Workload Identity Federation, so no key file exists. The config creation guide says creating a config can take several minutes, up to ten for a complex one, so give the job a generous timeout. The gateway update follows a zero-downtime model, with the caveat that some requests may still be handled by the previous config while the new one rolls out. Every deploy leaves a config behind; they are harmless, but a scheduled job that deletes all but the last twenty (never the one in use) keeps listings readable.
At the time of writing, API Gateway pricing is per API call per billing account: the first 2 million calls a month are free, then $3.00 per million up to 1 billion, then $1.50 per million. At 100 million calls a month that is roughly $294 on top of Cloud Run. The mechanism that surprises people is CORS: preflight requests pass through the gateway as calls in their own right, so a browser client can nearly double the count for non-simple requests. An Access-Control-Max-Age header on preflight responses lets browsers cache them.
Traps the generator cannot catch#
The generator checks shape, not behaviour. These are the failures that still get through, and what to do about each.
A preflight rejected before it reaches the backend. Browsers send an OPTIONS preflight with no Authorization header and no API key. With allowCors: true in x-google-endpoints, the gateway passes CORS requests through to your backend, which has to answer them. The name in that extension must match the API's managed service name, which is why host lives in the environment file. The failure to watch for is a hand-written OPTIONS operation that inherits an auth requirement or a per-operation quota: the rejection carries no CORS headers, so the browser reports a CORS error and hides the real status. If you add explicit OPTIONS operations, give them "security": [].
Deadlines. The default backend deadline is 15 seconds, configurable per x-google-backend, with a lower maximum of 600 seconds on non-streaming gateways. Upload or export endpoints that legitimately take longer need a deadline. Let fragments set an allow-listed deadline field and have the generator copy it across, rather than allowing the whole x-google-backend block back in.
A valid spec pointing at the wrong service. A route mapped to the wrong backend passes every check. A post-deploy smoke test that calls one public and one authenticated route per service catches most of these within a minute.
Breaking changes during a rollout. While a config rolls out, old and new serve side by side, and old mobile clients keep calling old routes for months. Keep route changes additive: add the new path, migrate clients, remove the old path in a later deploy.
Where this stops being the right tool#
If your API is one Cloud Run service, you probably do not need API Gateway: the service can verify tokens itself, and a load balancer with a serverless network endpoint group gives you a custom domain and Cloud Armor. If every service already publishes its own OpenAPI document from code, generating the gateway spec from those documents is a better source of truth than hand-written fragments. And if you need request transformation, per-consumer rate limiting or a developer portal, API Gateway is the wrong layer. The generator pattern still applies to whatever replaces it, since every gateway consumes a spec that is better built than typed.
Related articles
All articles →A practical split for small teams: coarse per-client limits at the edge, per-user and per-cost limits in the service, and the 429 behaviour both must share.
11 min
A feature-flag vendor is more than a small team needs. One Firestore document, a short in-memory cache and safe defaults give you kill switches and rollouts.
11 min
Define each request and response shape once. Get runtime validation, compile-time types and the OpenAPI document from the same object, with CI to prove it.
12 min