--- title: "OpenAPI-Native API Gateway" description: "Zuplo's gateway config IS an OpenAPI document. Routes, policies, handlers, validation, and the developer portal all derive from one spec. OpenAPI 3.0/3.1, YAML or JSON, with overlays for environment-specific config and edge-enforced request validation." canonicalUrl: "https://zuplo.com/features/open-api" sourceUrl: "https://zuplo.com/features/open-api" pageType: "feature" generatedAt: "2026-08-03" --- # Your spec is the gateway > When your spec, your gateway config, and your docs are three separate things, > they drift — and customers notice. Zuplo makes one OpenAPI document drive > routing, validation, docs, and SDKs, so what you publish always matches your > API. ## Why this matters: when the spec is just a doc, every artifact drifts OpenAPI works when it's the source of truth — for routes, validation, docs, SDKs, and tests. The moment it becomes "the file we wrote for the SDK generator," the rest of your stack stops trusting it. - **Spec, gateway, and docs disagree** — The OpenAPI spec is for clients. The gateway config is for routing. The portal is hand-curated. Three definitions of "the API" — when one of them drifts, customers feel it. - **Bad payloads reach your origin** — Clients send malformed JSON, missing required fields, wrong types. The gateway forwards everything. Your service spends compute returning 400s the gateway should have caught. - **Hand-edited routes file** — Engineers maintain `routes.json` next to the OpenAPI spec, copy-pasting paths and praying nobody forgets. The next API change touches three files instead of one. - **Vendor-locked spec extensions** — Your gateway adds proprietary fields the rest of the OpenAPI ecosystem doesn't understand. Spectral lints fail, Speakeasy generators choke, the spec only works in the gateway's own portal. ## What you get: one spec, many artifacts, always in sync - **One spec drives everything** — Routes, request validation, the developer portal, and exported client SDKs all read from `routes.oas.json`. Update the spec once — every artifact stays in lockstep. No drift between docs and behavior. - **Edge-enforced validation** — The `request-validation-inbound` policy checks bodies, query params, path params, and headers against your schema before the request reaches your origin. Reject, log-only, or both — per-route. Bad payloads get a structured 400 with field-level errors. - **Vendor-neutral by default** — Any valid OpenAPI document is valid Zuplo config. `x-zuplo-*` extensions are optional. Export a clean spec via the `openApiSpecHandler` and feed Spectral, Speakeasy, RateMyOpenAPI, or any other OpenAPI-aware tool. ## Validate at the edge. Overlay per environment. Attach `request-validation-inbound` to reject malformed payloads before they touch your origin. Use overlays in CI to produce environment-specific variants from one canonical spec. **Edge validation policy** ```json { "name": "open-api-validation-inbound", "policyType": "request-validation-inbound", "handler": { "export": "RequestValidationInboundPolicy", "module": "$import(@zuplo/runtime)", "options": { "validateBody": "reject-and-log", "validateQueryParameters": "reject-and-log", "validatePathParameters": "reject-and-log", "validateHeaders": "log-only" } } } # Reject response (HTTP 400): # { # "type": ".../validation", # "title": "Request body is invalid", # "status": 400, # "errors": [{ "field": "items[0].id", "message": "is required" }] # } ``` **Environment overlay · CI** ```bash # package.json "scripts": { "build:openapi:dev": "zuplo openapi overlay -i routes.oas.json \ -o overlays/dev.yaml -O dist/dev.oas.json", "build:openapi:prod": "zuplo openapi overlay -i routes.oas.json \ -o overlays/prod.yaml -O dist/prod.oas.json" } # overlays/prod.yaml overlay: 1.0.0 actions: - target: $.paths.*.*.x-zuplo-route.policies.inbound update: - rate-limit-prod - audit-log-export # CI deploys dist/prod.oas.json # Both share the same canonical spec. ``` Capabilities at a glance: - OpenAPI 3.0 / 3.1 - YAML or JSON - Edge validation - OpenAPI overlays - Spec export endpoint - Auto-generated dev portal ## What makes Zuplo different: OpenAPI as the contract, not as a side artifact - **OpenAPI Overlays in CI** — Run `npx zuplo openapi overlay --input … --overlay … --output …` to apply ordered actions via JSONPath. Inject `x-zuplo-route` into upstream specs you don't own. Produce dev/staging/prod variants from one canonical file. Watch mode for local iteration. - **Spec drives the developer portal** — Your OpenAPI doc drives a React-based developer portal — interactive playground, named examples, schema browser, multi-version support, custom MDX pages. Every spec change you'd make for documentation hygiene is a documentation upgrade automatically. - **Spec export for client SDKs** — Attach the `openApiSpecHandler` to a route and Zuplo serves a clean, vendor-neutral OpenAPI document — `x-zuplo-*` stripped, auth headers inferred from applied policies. Plug it into Speakeasy, OpenAPI Generator, or your team's preferred SDK pipeline. - **MCP via the same spec** — Mark an operation with `x-zuplo-route.mcp = { type: "tool" }` and the same spec that drives your routes and docs becomes the source of truth for your remote MCP server too. One artifact for human consumers, machine consumers, and AI consumers. ## What teams use this for **"Our team designs APIs in Stoplight. Can we ship the same spec to Zuplo?"** Yes. The Stoplight-authored spec is a valid Zuplo config as-is. Add `x-zuplo-route` extensions in an overlay file and run the overlay in CI. Stoplight stays the source of truth for design; Zuplo gets a runtime-ready spec without polluting the upstream repo. **"Our backend is rejecting bad payloads at runtime. Move that to the edge."** Add the `request-validation-inbound` policy to the affected routes, set `validateBody: reject-and-log`, and the gateway returns 400 with field-level errors before the request hits your service. Origin compute drops, error rates clean up, real bugs become easier to spot in your logs. **"The team wants generated TypeScript clients for our internal services."** Attach the `openApiSpecHandler` to `GET /openapi` and run Speakeasy or OpenAPI Generator against the URL. SDKs match what the gateway actually serves — including auth headers inferred from applied policies — without anyone hand-maintaining a separate client config. **"We need different rate limits in dev vs. prod, but one spec."** Maintain `routes.oas.json` as the canonical spec. Build `dev.overlay.yaml` and `prod.overlay.yaml` with environment-specific `x-zuplo-route.policies` blocks. Wire `build:openapi:dev` and `build:openapi` into `package.json` and CI applies the right overlay per environment. ## FAQ **What is OpenAPI and why does it matter for an API gateway?** OpenAPI is the industry-standard format for describing REST APIs — endpoints, request/response shapes, auth, examples. When your gateway, docs, validation, and SDKs all read from one OpenAPI document, you eliminate drift between code, runtime, and documentation. Zuplo takes this further: your OpenAPI file IS the gateway config, with x-zuplo-* extensions for handlers and policies. One file is the source of truth, not four. **Does Zuplo support OpenAPI 3.0 and 3.1?** Yes — both, in YAML or JSON. OpenAPI 3.1 is supported natively, 3.0 works as well, and OpenAPI 2.0 (Swagger) specs can be upgraded with standard tooling before import. Any valid OpenAPI document is a valid Zuplo configuration; vendor extensions (x-zuplo-*) attach Zuplo-specific behavior like policies and handlers without breaking spec validity. **How do I validate API requests against an OpenAPI schema?** Drop a request-validation policy on your routes and the gateway enforces required fields, types, formats, enums, and JSON Schema constraints from your OpenAPI spec — at the edge, before traffic reaches your origin. Invalid requests get a 400 with a structured problem-details body explaining the failure. Run in log-only mode first to find existing client bugs without breaking traffic. **Can I import an existing OpenAPI spec into a Zuplo gateway?** Yes. Importing an OpenAPI spec auto-creates routes from your operations. The original spec doesn't need any Zuplo extensions to start working — Zuplo treats it as the source of truth and adds runtime behavior via x-zuplo-route extensions you can layer on manually, through the Route Designer, or with OpenAPI Overlays. Migrating from another gateway becomes "export the spec, import it here." **What are OpenAPI overlays and how do I use them?** OpenAPI Overlays let you apply environment-specific or vendor-specific changes to a base spec without forking it. With Zuplo's CLI, run an overlay step in CI to inject Zuplo-specific config into a third-party spec, produce dev/staging/prod variants from one canonical file, or layer custom auth on top of an upstream spec you don't own. When the upstream changes, your overlay reapplies cleanly. **How do I auto-generate API docs from OpenAPI?** Point your developer portal at your OpenAPI document. Zuplo's portal renders the full reference, including a "Try it" panel that hits your live API with the user's API key. Schemas, examples, descriptions, and parameter constraints flow from the spec; MDX pages handle guides and tutorials. Edit the spec, deploy, the portal updates — no separate docs publishing step. **How do I generate client SDKs from an OpenAPI spec?** Zuplo can export your gateway config as a clean OpenAPI document with all vendor extensions stripped. Pipe that into Speakeasy, OpenAPI Generator, RateMyOpenAPI, or any SDK tool — the output is just standard OpenAPI. Client libraries, server stubs, and Postman collections all derive from the same file the gateway runs on, so your SDKs never drift from your API. **What's the best API gateway for OpenAPI?** Look for: OpenAPI as the actual config format (not as an export), 3.1 + 3.0 support, request validation against the spec at the edge, auto-generated developer portal, OpenAPI Overlays for environment variants, and clean spec export for SDK generation. Zuplo is one of the few gateways where OpenAPI is the source of truth — gateway, validation, docs, and SDKs all read from one file. Read the [OpenAPI guide](https://zuplo.com/docs/articles/openapi) or talk to an expert for migration help. ## Next steps - Start a free Zuplo account and import your OpenAPI spec: https://portal.zuplo.com/signup - Read the [OpenAPI docs](https://zuplo.com/docs/articles/openapi) - See the [Developer Portal](/features/developer-portal)