---
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. Learn how this
  works."
canonicalUrl: "https://zuplo.com/features/open-api"
sourceUrl: "https://zuplo.com/features/open-api"
pageType: "feature"
generatedAt: "2026-09-04"
---

# Your spec is the gateway

> When your spec, your gateway config, and your docs are three separate things,
> they drift — and customers notice. Make 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.
```

Vendor-neutral OpenAPI, enforced at the edge, covers:

- 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

Common questions about OpenAPI on Zuplo.

**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 or talk to an expert for migration help.

## Next steps

- Start for Free — https://portal.zuplo.com/signup
- Read the Docs — https://zuplo.com/docs/articles/openapi
- See the Developer Portal — /features/developer-portal