Die OpenAPI-Toolchain, die ich gebaut habe: Eine Spec, kein Runtime, dir gehört die Ausgabe

Du füllst ein Formular aus. Lässt das Namensfeld leer. Klickst auf Senden. „Name ist erforderlich” erscheint neben dem Feld. Kein Netzwerk-Request wurde abgeschickt. Der generierte Client hat CreatePetRequestSchema.strip().parse(body) aufgerufen, bevor überhaupt etwas rausging.

Du trägst den Namen ein. Klickst erneut auf Senden. Der POST landet im Hono-Router. Der Router ruft CreatePetRequestSchema.safeParse(body) auch serverseitig auf: dasselbe Schema, dieselben Regeln, dieselbe Fehlerstruktur. Diesmal valide: 201, das Tier erscheint in der Liste.

Davon wurde kein einziger Code von Hand geschrieben. Der Router, beide Schema-Aufrufe, die TypeScript-Typen, der React-Hook, all das kam aus einem einzigen Befehl gegen eine einzige Spec-Datei. Beide Seiten werden von derselben schemas.ts gesteuert.

Das ist der Petstore. Er ist die Demo für openapi-zod-ts, die OpenAPI-Toolchain, die ich angefangen habe zu bauen, nachdem ich einen Monat auf den Merge eines PRs gewartet hatte und beschloss, nicht länger zu warten.

Vier Pakete haben gerade stabile Releases erreicht. Das hier ist der tiefe Einblick: was sie tatsächlich generieren, die Design-Entscheidungen dahinter und ein ehrlicher Vergleich mit den Alternativen. (Ich habe das auch meinem eigenen Team bei der Arbeit gezeigt und ein klares Nein kassiert. Diese Geschichte, und was ich am Tool deswegen geändert habe, ist ein eigener Beitrag.)

---

Was es generiert

Eine Spec-Datei. Vier Generatoren. So ist die Aufteilung:

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)

Ein viertes Paket, api-errors, generiert nichts: es mappt RFC-9457-Problem-Detail-Responses auf Formularfeld-Fehler. React-Hook-Form-Adapter inklusive. Kein generierter Code, reines Runtime.

openapi-gen generiert TypeScript-Interfaces für jedes Schema und eine async-Funktion pro 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> { ... }

Natives fetch. Kein Axios, kein Wrapper. Optionaler per-Request-Config-Override für SSR. Die generierte Funktionssignatur entspricht exakt deiner Spec: nicht mehr und nicht weniger.

openapi-server generiert das Service-Interface, das deine Implementierung erfüllen muss, sowie den Hono-Router, der alles zusammenführt:

// 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 { ... }

Du implementierst PetstoreService. TypeScript sagt dir zur Compile-Zeit, wenn deine Implementierung von der Spec abweicht. Der Router übernimmt die HTTP-Schicht. Route-Handler schreibst du nie.

openapi-react-query generiert typisierte 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), ... })
}

Die Key-Factories werden ebenfalls generiert, also funktioniert queryClient.invalidateQueries({ queryKey: petKeys.list() }) einfach: die Factory ist Teil des Vertrags, nicht etwas, das du separat schreibst.

Außerdem wird immer eine test-utils.ts neben den Hooks generiert, ganz ohne neue 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) { ... }

Einen generierten Hook zu testen heißt renderHook(() => useListPets(), { wrapper: createWrapper(createTestQueryClient()) }), kein selbstgebauter QueryClient-Boilerplate, keine manuellen Mocks. Wenn du keine Hook-Tests schreibst, entfernt der Bundler die Datei per Tree-Shaking. Diese Idee kam direkt aus einem Code-Review, auf das ich später zurückkomme.

---

Die Zod-Geschichte

Das ist der Teil, der den gesamten Stack zusammenhält.

Beim ersten pnpm generate legt openapi-gen eine schemas.ts aus deiner Spec an. Danach rührt es die Datei nie wieder an:

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

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

Du bearbeitest sie. Du besitzt sie. Der Generator überschreibt sie nie:

// 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'),
})

Dann zeigst du beide Config-Dateien auf 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" }

Beim nächsten Generate wird der Router mit deiner eingebauten Validierung neu generiert:

// 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)
})

Der Generator hat CreatePetRequestSchema gefunden, es in die Route eingebaut, und jetzt erreichen ungültige Requests nie deine Service-Logik. Client-seitige und server-seitige Validierung nutzen identische Regeln aus derselben Datei. Das ist der Round-Trip aus der Einleitung.

---

Die Design-Entscheidungen

Jedes Tool in diesem Bereich hat andere Tradeoffs gemacht. Hier ist, worauf meines gesetzt hat, und warum.

Kein Runtime-Footprint. Jedes Paket ist eine devDependency oder generiert Code, der nur das nutzt, was dein Projekt bereits hat. Die Ausgabe von openapi-gen nutzt fetch. Die Ausgabe von openapi-react-query nutzt React Query, das du bereits hast. Die Ausgabe von openapi-server nutzt Hono, das du bereits hast. Niemand schmuggelt eine neue Dependency in dein Production-Bundle.

Die Alternative, einen Runtime-Adapter mitzuliefern, macht die Integration einfacher, erzeugt aber eine Kopplung, die sich schwer rückgängig machen lässt. Wenn die Adapter-Version hinter der Bibliothek zurückbleibt, die sie umhüllt (das passiert mit jedem hey-api-Release-Zyklus), bist du blockiert.

Du besitzt die Ausgabe. Der generierte Code ist lesbares TypeScript, das du reviewen, committen und anpassen kannst. Keine undurchsichtige Abstraktion. Nicht minifiziert. Nicht in eine Klassenhierarchie gepackt, die du nicht wolltest. Wenn dir eine generierte Funktionssignatur nicht gefällt, kannst du genau nachlesen, was sie tut, und entscheiden, ob du den Generator anpasst oder einen dünnen Wrapper schreibst.

Nur das Neueste. TypeScript 6, OpenAPI 3.1, Zod v4, React Query v5. Keine Backports. Klare Schnitte bedeuten weniger Code, weniger Testfläche, weniger „Unterstützt diese Version X?”-Probleme. Wer einen älteren Stack hat, ist hier falsch, und ich sage das lieber offen, als eine Kompatibilitätsmatrix zu pflegen.

Prettier-saubere Ausgabe von Haus aus. Jede generierte Datei besteht prettier --check beim Generieren. Kein Rauschen in Diffs beim Regenerieren. Committen, linten, deployen.

---

Der ehrliche Vergleich

Drei Tools lösen verwandte Probleme. Hier ist, wofür sich jedes entschieden hat:

openapi-typescript generiert TypeScript-Typen aus einer OpenAPI-Spec. Nur Typen, kein Client. Das components["schemas"]-Zugriffsmuster ist die typische Reibung: Um einen Typ zu verwenden, schreibst du überall components["schemas"]["Pet"], oder du legst dir einen Alias an. Die Ausgabe ist präzise und schnell erzeugt. Der Tradeoff: Die Fetch-Schicht schreibst du weiterhin selbst. Es ist eine Typen-Grundlage, kein Client.

Update: Mein PR für TypeScript-6-Unterstützung lag sechs Wochen offen. Jemand bot 250 $ Sponsoring an, damit er gemergt wird. Er ist immer noch offen. Das Projekt ist nicht verlassen, nur langsam.

hey-api generiert Typen, einen Client und Hooks. Die funktionsreichste Option. Der Tradeoff: Runtime-Adapter erforderlich (das @hey-api/client-fetch-Paket landet in deinem Bundle), und häufige Breaking Changes über Releases hinweg. Sie entwickeln schnell. Wer ihre Richtung mag, ist gut aufgehoben, aber du akzeptierst das Upgrade-Laufband.

orval generiert aus OpenAPI 2 und 3, unterstützt mehrere Frameworks und Client-Bibliotheken. Sehr konfigurierbar. Der Tradeoff ist die Konfiguration selbst: du stellst viele Optionen ein, bevor irgendetwas so funktioniert, wie du es willst. Die Ausgabequalität ist gut, sobald du alles eingestellt hast.

Die Lücke, die keines davon sauber gefüllt hat: kein Runtime-Footprint + generiertes Server-Interface + Zod-Validierung automatisch in den Router eingebaut. Diese Kombination habe ich gebraucht. Das ist es, was das hier ist.

---

Mit echten Specs getestet

Der Petstore hat 3 Pfade. Er demonstriert den Round-Trip. Er beweist nicht, dass der Generator mit APIs in Produktionsgröße umgehen kann.

Deshalb liefert das Repo eine Kompatibilitätsmatrix mit: 128 echte OpenAPI-Specs, alle laufen bei jedem PR in der CI. 128/128 generieren ohne Fehler. Diese Suite zu bauen hat den Generator nicht nur validiert: der erste Schwung fand 7 Bugs, alle behoben, bevor die Examples in main gelandet sind. Genau dafür ist eine echte Kompatibilitätssuite da.

Elf dieser 128 sind Showcase-Specs: ihre vollständige generierte Ausgabe liegt im Repo committed und wird bei jedem relevanten PR auf Drift geprüft, sodass eine Regression als Diff auftaucht und nicht als stiller Fehler. Sie decken die ganze Spannbreite ab:

Spec	OAS-Version	Pfade
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 ist der Stresstest: ein Pfad, über 100 Query-Parameter. Genau die Art von Grenzfall, die naiven Param-Handling-Code bricht. Resend und OpenAI laufen beide auf OAS 3.1: die gesamte Spannbreite von minimalen Beispielen bis zu 160+ Pfaden ist abgedeckt. OpenAIs Spec testet die obere Grenze der Skalierung.

Saubere Ausgabe ist nicht die einzige Hürde. Eine separate Smoke-Suite generiert Clients gegen neun freie öffentliche APIs und feuert dann echte HTTP-Requests durch sie hindurch: der Beweis, dass der generierte Code nicht nur kompiliert, sondern tatsächlich mit einem Live-Server spricht. Und der Petstore fährt bei jedem PR einen vollständigen Playwright-E2E, der den Browser-zu-Server-Round-Trip aus der Einleitung dieses Beitrags durchläuft. Kompiliert, spricht, Round-Trip: drei verschiedene Arten, falsch zu sein, drei verschiedene Gates.

---

Was mein eigenes Team sagte

Ich habe das bei der Arbeit vorgestellt, wo wir es für eine TypeScript-Migration evaluiert haben. Die Antwort war ein berechtigtes Nein: Single-Maintainer, zu frisch, außerhalb des Scopes für eine Adoption. Ich habe nicht widersprochen und nicht gedrängt.

Dieses Nein, und was ich danach auf eigene Faust daraus gemacht habe, inklusive der test-utils.ts von weiter oben, entpuppte sich als die interessantere Geschichte. Das bekommt einen eigenen Beitrag: Ich habe eine OpenAPI-Toolchain gebaut. Mein eigenes Team hat sie abgelehnt.

---

Hinweis für Agenten

Ein Design-Ziel, das es wert ist, benannt zu werden: agenten-freundlich.

Wirf das in ein Cursor- oder Claude-Code-Projekt, zeig es auf deine Spec, und das Modell hat einen vollständig typisierten Client in etwa der Zeit, die es braucht, um die Config zu lesen: npx openapi-gen, nichts Zusätzliches installiert. Die Ausgabe ist lesbares TypeScript, keine Black Box, also kann der Agent über eine Funktion nachdenken, die er aufgerufen hat, statt eine Abstraktion zu erraten. Und weil schemas.ts eine schlichte Datei getrennt von der Generierungs-Pipeline ist, kann der Agent eine Validierungsregel verschärfen, ohne den Generator überhaupt zu verstehen: Zod bearbeiten, regenerieren, fertig.

Das ist genau die Eigenschaft, die sich auch ein menschlicher Reviewer wünscht: eine devDependency, ein Befehl, eine Ausgabe, die du lesen und der du vertrauen kannst. Der Agent muss nicht wissen, wie der Generator funktioniert. Er braucht eine Ausgabe, die korrekt, lesbar und sicher zu bearbeiten ist. Alle anderen auch.

---

Stand der Dinge

Alle vier Pakete sind seit dieser Woche stabil:

Paket	Version	Was es tut
@codewithagents/openapi-gen	4.1.0	Typen + 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	Formularfehler-Mapping

Prettier-saubere Ausgabe ist bei jedem Generate garantiert. Der Petstore-E2E läuft in der CI: Playwright deckt den Browser-zu-Server-Round-Trip in jedem PR ab. Es gibt einen Mutation-Score, den ich veröffentliche, auch wenn er unangenehm ist.

Die gesamte Pipeline liegt bei github.com/codewithagents/openapi-zod-ts. Der Petstore ist in packages/petstore: klonen, pnpm install, pnpm dev, und der Round-Trip aus der Einleitung läuft in weniger als zwei Minuten auf deinem Rechner.

Wenn du es ausprobierst und etwas nicht stimmt, meld ein Issue. Wenn dir etwas fehlt, das du brauchst, meld ein Issue. Der PR, der das alles ausgelöst hat, ist immer noch offen im Upstream-Repo.

Ich habe aufgehört zu warten.