The OpenAPI Toolchain I Built: One Spec, Zero Runtime, You Own the Output

You fill in a form. Leave the name field empty. Hit submit. “Name is required” appears next to the field. No network request fired. The generated client called CreatePetRequestSchema.strip().parse(body) before sending anything.

Fill it in. Hit submit again. The POST hits the Hono router. The router calls CreatePetRequestSchema.safeParse(body) on the server side too: same schema, same rules, same error shape. Valid this time: 201, the pet appears in the list.

None of that was written by hand. The router, both schema calls, the TypeScript types, the React hook, all of it came from one command against one spec file. The same schemas.ts governs both sides.

That’s the petstore. It’s the demo for openapi-zod-ts, the OpenAPI toolchain I started building after waiting a month for a PR to get merged and deciding to stop waiting.

Four packages just hit stable releases. This is the deep dive: what they actually generate, the design bets behind them, and an honest comparison with the alternatives. (I also showed this to my own team at work and got a flat no. That story, and what I changed in the tool because of it, is its own post.)

---

What it generates

One spec file. Four generators. Here’s the split:

spec/api.json
  ├── openapi-gen          → models.ts, client.ts         (types + fetch client)
  ├── openapi-server       → service.ts, router.ts        (server interface + Hono router)
  └── openapi-react-query  → hooks.ts                     (React Query v5 hooks)

A fourth package, api-errors, doesn’t generate anything: it maps RFC 9457 problem detail responses to form field errors. React Hook Form adapter included. Zero generated code, pure runtime.

openapi-gen generates TypeScript interfaces for every schema and one async function per operation:

// models.ts: generated
export interface Pet {
  id: string
  name: string
  species: string
}

// client.ts: generated
export async function createPet(
  body: CreatePetRequest,
  config?: Partial<ClientConfig>
): Promise<Pet> { ... }

Native fetch. No axios, no wrapper. Optional per-request config override for SSR. The generated function signature matches your spec: nothing more, nothing less.

openapi-server generates the service interface your implementation must satisfy, and the Hono router that wires it together:

// service.ts: generated
export interface PetstoreService {
  listPets(params?: { species?: string }): Promise<Pet[]>
  createPet(body: CreatePetRequest): Promise<Pet>
  getPet(id: string): Promise<Pet>
  deletePet(id: string): Promise<void>
}

// router.ts: generated
export function createRouter(service: PetstoreService): Hono { ... }

You implement PetstoreService. TypeScript tells you at compile time if your implementation drifts from the spec. The router handles the HTTP layer. You never write route handlers.

openapi-react-query generates typed React Query v5 hooks:

// hooks.ts: generated
export function useListPets(params?: { species?: string }, options?: ...) {
  return useQuery({ queryKey: petKeys.list(params), queryFn: () => listPets(params), ... })
}

export function useCreatePet(options?: ...) {
  return useMutation({ mutationFn: (vars) => createPet(vars), ... })
}

The key factories are generated too, so queryClient.invalidateQueries({ queryKey: petKeys.list() }) just works: the factory is part of the contract, not something you write separately.

It also generates a test-utils.ts next to the hooks, always, with zero new dependencies:

// test-utils.ts: generated alongside hooks.ts
export function createTestQueryClient(): QueryClient {
  return new QueryClient({
    defaultOptions: {
      queries: { retry: false, gcTime: 0 },
      mutations: { retry: false },
    },
  })
}

export function createWrapper(queryClient: QueryClient) { ... }

Testing a generated hook means renderHook(() => useListPets(), { wrapper: createWrapper(createTestQueryClient()) }), no hand-rolled QueryClient boilerplate, no manual mocks. If you don’t write hook tests, the bundler tree-shakes the file away. This one came out of my own hunt for boilerplate to delete, more on that in the companion post.

---

The Zod story

This is the part that ties the full stack together.

On the first pnpm generate, openapi-gen bootstraps a schemas.ts from your spec. Then it stops touching it:

// generated/schemas.ts: bootstrapped once, then yours
import { z } from 'zod'

export const CreatePetRequestSchema = z.object({
  name: z.string(),
  species: z.string(),
})

You edit it. You own it. The generator never overwrites it:

// After you add validation rules
export const CreatePetRequestSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  species: z.string().min(1, 'Species is required'),
})

Then you point both config files at input_schema: "generated/schemas.ts":

// openapi-gen.config.json
{ "input_openapi": "spec/api.json", "output": "generated/", "input_schema": "generated/schemas.ts" }

// openapi-server.config.json
{ "input_openapi": "spec/api.json", "output": "generated/", "framework": "hono", "input_schema": "generated/schemas.ts" }

On the next generate, the router is regenerated with your validation wired in:

// router.ts: regenerated, now with your schema
app.post('/pets', async (c) => {
  const body = await c.req.json()
  const parseResult = CreatePetRequestSchema.safeParse(body)
  if (!parseResult.success) {
    return c.json({ error: 'Invalid request body', issues: parseResult.error.issues }, 422)
  }
  return c.json(await service.createPet(parseResult.data), 201)
})

The generator found CreatePetRequestSchema, wired it into the route, and now invalid requests never reach your service logic. Client-side and server-side validation use identical rules from the same file. That’s the round-trip from the opening.

---

The design bets

Every tool in this space made different tradeoffs. Here’s what mine bet on, and why.

Zero runtime footprint. Every package is a devDependency or generates code that only uses what your project already has. openapi-gen output uses fetch. openapi-react-query output uses React Query, which you already have. openapi-server output uses Hono, which you already have. Nobody sneaks a new dependency into your production bundle.

The alternative, shipping a runtime adapter, makes integration easier but creates a coupling you can’t easily remove. When the adapter version lags the library it wraps (this happens with every hey-api release cycle), you’re blocked.

You own the output. The generated code is readable TypeScript you can review, commit, and modify. Not an opaque abstraction. Not minified. Not wrapped in a class hierarchy you didn’t ask for. If you don’t like a generated function signature, you can read exactly what it does and decide whether to patch the generator or write a thin wrapper.

Latest only. TypeScript 6, OpenAPI 3.1, Zod v4, React Query v5. No backports. Opinionated cuts mean less code, less testing surface, fewer “does this version support X?” issues. If you’re on an older stack, this isn’t the tool for you, and I’d rather be honest about that than ship a compatibility matrix.

Prettier-clean output by default. Every generated file passes prettier --check on generation. No noisy diffs when you regenerate. Commit it, lint it, ship it.

---

The honest comparison

Three tools solve adjacent problems. Here’s what each one chose:

openapi-typescript generates TypeScript types from an OpenAPI spec. Types only, no client. The components["schemas"] access pattern is the defining friction: to use a type you write components["schemas"]["Pet"] everywhere, or you alias it. The generated output is accurate and fast to produce. The tradeoff: you still write the fetch layer yourself. It’s a types foundation, not a client.

Update: my PR for TypeScript 6 support sat open for six weeks. Someone offered $250 in sponsorship to get it merged. It’s still open. The project isn’t abandoned, just slow.

hey-api generates types, a client, and hooks. The most feature-complete option. The tradeoff: runtime adapter required (the @hey-api/client-fetch package ships in your bundle), and frequent breaking changes across releases. They’re moving fast. If you like their direction, great, but you’re accepting the upgrade treadmill.

orval generates from OpenAPI 2 and 3, supports multiple frameworks, multiple client libraries. Very configurable. The tradeoff is the configuration itself: you tune a lot of options before anything works the way you want. The output quality is good once you’ve dialed it in.

The gap none of them filled cleanly: zero runtime footprint + generated server interface + Zod validation wired into the router automatically. That combination is what I needed. It’s what this is.

---

Tested against real-world specs

The petstore is 3 paths. It demonstrates the round-trip. It doesn’t prove the generator handles production-scale APIs.

So the repo ships a compatibility matrix: 128 real-world OpenAPI specs, all run in CI on every PR. 128/128 generate without errors. Building that suite didn’t just validate the generator: the first batch found 7 bugs, all fixed before the examples landed in main. That’s what a real compatibility suite is for.

Eleven of those 128 are showcase specs: their full generated output is committed to the repo and drift-checked on every relevant PR, so a regression shows up as a diff, not a silent failure. They span the range:

Spec	OAS version	Paths
Redocly Museum	3.1.0	5
1Password Connect	3.0.2	11
Petstore 3.0	3.0.4	13
Adyen LegalEntity	3.1.0	20
Adyen Checkout	3.1.0	26
Resend	3.1.0	47
DEV.to / Forem	3.0.3	49
Open-Meteo	3.0.0	1
Spotify	3.0.3	71
Twitter/X	3.0.0	67
OpenAI	3.1.0	160+

Open-Meteo is the stress test: one path, over 100 query parameters. It’s the kind of edge case that breaks naive param-handling. Resend and OpenAI both run on OAS 3.1: the whole range from minimal examples to 160+ paths is covered. OpenAI’s spec tests the upper bound of scale.

Clean output isn’t the only bar. A separate smoke suite generates clients against nine free public APIs and then fires real HTTP requests through them: proof the generated code doesn’t just compile but actually talks to a live server. And the petstore runs a full Playwright E2E on every PR, driving the browser-to-server round-trip from the opening of this post. Compiles, talks, round-trips: three different ways of being wrong, three different gates.

---

What my own team said

I showed this at work, where we were evaluating it for a TypeScript migration. The answer was a reasonable no: single maintainer, too fresh, out of scope to adopt. I didn’t argue and I didn’t push.

That no, and what I did with it on my own afterwards, including the test-utils.ts above, turned out to be the more interesting story. It gets its own post: I Built an OpenAPI Toolchain. My Own Team Rejected It.

---

Agentic note

One design goal worth naming: agent-friendly.

Drop this into a Cursor or Claude Code project, point it at your spec, and the model has a fully-typed client in about the time it takes to read the config: npx openapi-gen, nothing extra installed. The output is readable TypeScript, not a black box, so the agent can reason about a function it called instead of guessing at an abstraction. And because schemas.ts is a plain file separate from the generation pipeline, the agent can tighten a validation rule without understanding the generator at all: edit the Zod, regenerate, done.

That’s the same property a human reviewer wants: one devDependency, one command, output you can read and trust. The agent doesn’t need to know how the generator works. It needs the output to be correct, readable, and safe to edit. So does everyone else.

---

Where it stands

All four packages are stable as of this week:

Package	Version	What it does
@codewithagents/openapi-gen	4.1.0	Types + fetch client
@codewithagents/openapi-react-query	3.3.1	React Query v5 hooks + test-utils
@codewithagents/openapi-server	1.1.0	Server interface + Hono router
@codewithagents/api-errors	1.0.3	Form error mapping

Prettier-clean output is guaranteed on every generate. The petstore e2e runs in CI: Playwright covering the browser-to-server round-trip in every PR. There’s a mutation score that I publish even when it’s uncomfortable.

The full pipeline lives at github.com/codewithagents/openapi-zod-ts. The petstore is in packages/petstore: clone, pnpm install, pnpm dev, and the round-trip from the opening is running on your machine in under two minutes.

If you try it and find something wrong, file an issue. If you find something missing that you need, file an issue. The PR that started all of this is still open on the upstream repo.

I stopped waiting for it.