Ich habe eine OpenAPI-Toolchain gebaut. Mein eigenes Team hat sie abgelehnt.

An ein paar Abenden habe ich eine OpenAPI-Toolchain gebaut, die unseren Job besser erledigte als die Bibliothek, von der wir ohnehin schon abhingen. Es ist ein Seitenprojekt, gebaut neben einem Vollzeitjob. Dann habe ich sie meinem Team gezeigt, und die haben mir gesagt, ich solle sie nicht verwenden.

Die Nachricht war höflich und vollkommen nachvollziehbar:

“Diese neue Dependency ist sehr frisch und wird nur von 1 Person gepflegt (dir). Es fühlt sich an, als würden wir diese Dependency für unser Team adoptieren, und das liegt eindeutig außerhalb unseres Scopes.”

Sie hatten recht. Und genau das ist der Teil, der eine Geschichte wert ist.

Warum ich sie überhaupt gebaut habe

Wir starteten eine TypeScript-Migration auf Basis von openapi-typescript. Es unterstützte TypeScript 6 noch nicht, also habe ich einen Pull Request aufgemacht, um genau das hinzuzufügen.

Der PR blieb liegen. Sechs Wochen offen. Jemand bot 250 $ Sponsoring an, damit er gemergt wird. Er ist bis heute offen. Das Projekt ist nicht verlassen, nur langsam, und “langsam” reichte aus, um eine Migration mit Deadline zu blockieren.

Also habe ich abends mein eigenes gebaut: openapi-zod-ts, vier Pakete, die aus einer einzigen OpenAPI-Spec einen vollständig typisierten Client, ein Server-Interface, React-Query-Hooks und in den Router eingebaute Zod-Validierung machen. Es konnte schon mehr als die Bibliothek, die es ersetzen sollte. Wenn dich die Architektur interessiert, dazu gibt es einen eigenen tiefen Einblick. In diesem Beitrag geht es darum, was passierte, als ich es mit zur Arbeit brachte.

Das Nein war fair

Ich brachte es als Kandidaten für die Migration ins Spiel. Die Antwort war nein, aus dem oben zitierten Grund: Single Maintainer, kaum eine Woche alt, und es zu adoptieren heißt, mich zu adoptieren.

Ich habe nicht widersprochen, weil der Einwand stimmt. Der Bus-Faktor ist eins. Das Projekt war Tage alt. Wenn mich ein Bus überfährt oder mir einfach langweilig wird, hat das Team eine Dependency, die sonst niemand versteht. Das sind echte Kosten, und etwas anderes zu behaupten wäre unehrlich.

Was ich erwidert habe, ein Mal

Hier ist das Argument, das ich trotzdem gebracht und dann fallen gelassen habe.

Die bestehenden Bibliotheken sind in keiner besseren Position. hey-api ist eine oder zwei Personen, die schnell vorangehen, mit häufigen Breaking Changes. openapi-typescript hat meinen TS-6-PR ungemergt liegen, mit einem 250-$-Bounty drauf. Keine davon ist eine gut finanzierte Wartungsgeschichte über mehrere Organisationen hinweg. Es sind Einzelpersonen, die Open Source in ihrer Freizeit pflegen, genau wie meine. “Single Maintainer” ist nicht der Unterschied zwischen meinem Tool und einer sicheren Wahl. Es ist die Ausgangslage für die ganze Kategorie.

Und openapi-zod-ts ist MIT-lizenziert. Wenn ich aufhöre, es zu pflegen, forkt es das Team. Das ist der gesamte Sinn der Lizenz. Die Ausgabe ist lesbares TypeScript, das dir gehört, kein undurchsichtiges Runtime, das du mietest.

Dann habe ich aufgehört. Ich sagte: Hier ist das Tool, hier ist der Vergleich, ihr entscheidet. Ich werde es nicht erzwingen. Einem Team eine Dependency aufzudrängen, das sie nicht will, ist genau der Weg, um zu dem Single Point of Failure zu werden, vor dem sie Angst hatten.

Also habe ich es stattdessen unbestreitbar gemacht

Nach dem Nein ist das Team weitergezogen. Kein Review, keine Nachfragen, kein zweites Gespräch. Fair genug: Ich hatte mein Argument einmal vorgebracht, sie hatten ihre Entscheidung getroffen, und ich hatte nicht vor, es neu aufzurollen.

Aber ich konnte das Tool nicht lassen, wie es war. Nicht um irgendwen umzustimmen, niemand wartete auf eine Fortsetzung, sondern einfach, weil ich wusste, dass es noch nicht fertig war. Ein Code-Generator hat einen weiten Wirkungsradius: eine einzige subtile Regression betrifft jedes Projekt, das ihn ausführt. Wenn ich selbst weiter davon abhängen wollte, musste es sich dieses Vertrauen verdienen. Also habe ich ein paar weitere Abende investiert, nicht in Features, sondern in Qualität.

Ein paar Abende später hatte openapi-zod-ts eine:

• Nahezu 100 % Test-Coverage über alle vier Pakete, in der CI erzwungen. Ein PR, der die Coverage senkt, schlägt fehl.
• Eine 128-Spec-Kompatibilitätsmatrix. Der Generator läuft gegen 128 echte öffentliche Specs, Stripe, GitHub, OpenAI, Adyen, Spotify, Twilio und über 120 weitere. 128/128 generieren bei jedem PR ohne Fehler.
• Smoke-Tests gegen echte öffentliche APIs. Der generierte Client feuert bei jedem Push auf main echte HTTP-Requests gegen echte Server, nicht nur einen “kompiliert es überhaupt”-Check.
• Mutation-Testing mit Stryker, das den Quellcode absichtlich kaputt macht, um zu beweisen, dass die Tests Regressionen tatsächlich abfangen. Hohe Coverage, die keine Bugs fängt, fliegt hier auf.
• Ein Full-Stack-Playwright-E2E. Eine Spec treibt eine lauffähige Petstore-App, vom Browser bis zum Server, und der gesamte Round-Trip läuft bei jedem PR.
• Statische Analyse bei jedem PR über Fallow und CodeQL.

Das ist jetzt der Why Quality Matters-Abschnitt im Repo. Niemand hat danach gefragt. Ich habe es geschrieben, weil die Alternative gewesen wäre, etwas auszuliefern, von dem ich wusste, dass es leise kaputtgehen konnte, und damit konnte ich nicht leben.

Dann bin ich auf die Jagd nach Boilerplate gegangen

Das Andere, woran ich nicht aufhören konnte zu denken, war, wie viel handgeschriebenen Code meine Dependency löschen könnte. Also habe ich mich auf die Suche nach Boilerplate gemacht, den ich erledigen konnte.

Die generierten React-Query-Hooks waren eine Quelle. Sie zu testen hieß, in jedem Projekt, das sie nutzte, dasselbe QueryClient-Setup und manuelle Mocks zu schreiben. Also gibt der Generator jetzt jedes Mal eine test-utils.ts neben den Hooks aus, ganz ohne neue Dependencies: einen vorkonfigurierten Test-QueryClient und einen Wrapper für renderHook. Ein Dutzend Zeilen Setup und handgeklöppelte Mocks schrumpfen auf eine einzige.

Stapel das über eine ganze API-Oberfläche, und es summiert sich. Der Proof-of-Concept-PR, den ich aufgemacht habe, kürzte den API-bezogenen Code um etwa 50 %. Die Hälfte des handgeschriebenen Client- und Testcodes, weg, ersetzt durch generierte Ausgabe, die du tatsächlich lesen kannst.

Was ich tatsächlich bekommen habe

Ein Seitenprojekt, nach Feierabend gebaut. Ich habe keine Adoption bekommen, und nach dem ersten Nein hat das Team kein weiteres Wort darüber verloren. Das ist ihre Entscheidung, und ich dränge nicht. Leuten eine Dependency aufzudrängen, die sie nicht wollen, ist genau der Weg, um zu dem Single Point of Failure zu werden, vor dem sie sich von Anfang an gefürchtet haben.

Was ich stattdessen bekommen habe: ein Tool, das den Job besser erledigt als die Bibliothek, die es ersetzt hätte, eine API-Schicht, die halb so viel Code ist, und die stille Genugtuung, etwas ordentlich zu Ende gebracht zu haben, als niemand mich darum gebeten hat. Es ist MIT, es liegt auf GitHub, und die Architektur ist dokumentiert, falls du sie je brauchst.

Der PR, der das alles ausgelöst hat, ist immer noch offen im Upstream. Ich habe aufgehört, darauf zu warten. Ich habe stattdessen etwas Besseres gebaut.