TypeScript OpenAPI Toolchain: Eine Woche, vier Packages, auf npm veröffentlicht

Das Problem

Ich startete eine TypeScript-Migration bei der Arbeit. Die Library, von der wir abhingen, openapi-typescript, unterstützte noch kein TypeScript 6. Ich öffnete einen Pull Request, um das hinzuzufügen.

Der PR lag sechs Wochen offen. Jemand bot 250 Dollar Sponsoring an, damit er gemerged wird. Er blieb offen.

Das reichte. Ich öffnete eine neue Session und begann, einen Ersatz zu bauen.

Der Ansatz

Das Ziel war klar: eine OpenAPI-Spec-Datei, ein Befehl, vollständig typisierter Full-Stack-Output. Keine Runtime-Dependencies. Kein undurchsichtiger Abstraktionslayer. Generierten Code, den man lesen, reviewen und committen kann.

Ich baute vier Packages: @codewithagents/openapi-gen für TypeScript-Interfaces und einen typisierten Fetch-Client, @codewithagents/openapi-server für ein generiertes Server-Interface und Hono-Router, @codewithagents/openapi-react-query für React-Query-v5-Hooks, und @codewithagents/api-errors für RFC-9457-Problem-Detail-Fehler-Mapping.

Die vollständige Architektur ist im Quell-Blogpost dokumentiert: The OpenAPI Toolchain I Built: One Spec, Zero Runtime, You Own the Output (englisch).

Die Kompatibilitätsmatrix

Das Repository liefert eine Kompatibilitätsmatrix: 128 echte OpenAPI-Specs, alle in CI bei jedem PR ausgeführt. Sie umfassen Stripe, GitHub, OpenAI, Adyen, Spotify, Twilio, Resend, Twitter/X und mehr als 120 weitere.

128/129 generieren ohne Fehler. Der eine Fehler war ein Spec mit einem bestätigten strukturellen Fehler upstream. Das Erstellen dieser Suite fand sieben Bugs im Generator, alle vor dem Merge in main behoben.

Was das Team sagte

Ich zeigte es bei der Arbeit. Die Antwort war Nein, höflich und völlig vernünftig: Einzelner Betreuer, kaum eine Woche alt, es anzunehmen bedeutet mich anzunehmen.

Sie lagen richtig. Ich argumentierte nicht dagegen. Was ich stattdessen tat: Weitere Abende damit verbringen, es unbestreitbar zu machen. Nahezu 100% Testabdeckung, in CI durchgesetzt. Mutations-Tests mit Stryker. Statische Analyse bei jedem PR. Die vollständige Geschichte des Neins und was danach kam (englisch) ist ein eigener Post.

Das Ergebnis

Vier stabile Packages auf npm. Eine 128-Spec-Kompatibilitätsmatrix in CI. Full-Stack Playwright E2E. Nahezu 100% Abdeckung. Mutations-Score öffentlich veröffentlicht, auch wenn er unbequem ist.

Ein Proof-of-Concept-PR schnitt API-bezogenen Code um etwa 50% zurück. Die Toolchain ist MIT-lizenziert und öffentlich auf GitHub unter github.com/codewithagents/openapi-zod-ts.

Was das für dein Team bedeutet

Die Frage, die diese Case Study beantwortet, ist nicht "solltest du diese Toolchain verwenden." Die Frage ist: Was wird möglich, wenn ein einzelner Engineer mit Freizeit und agentischen Workflows eine Qualitätsbibliothek produzieren kann, die mit etablierten Tools konkurriert?

Das Compound: Nicht "KI schreibt deinen Code." Das Compound ist, dass Qualitätsinfrastruktur, das Ding, das die meisten Engineers überspringen, weil es zu lange dauert, schnell genug wird, um sie tatsächlich zu bauen.