I Built an OpenAPI Toolchain. My Own Team Rejected It.

Over a handful of evenings, I built an OpenAPI toolchain that did our job better than the library we were already depending on. It is a side project, built around a full-time job. Then I showed it to my team, and they told me not to use it.

The message was polite and completely reasonable:

“This new dependency is very fresh and only maintained by 1 person (you). It feels like adopting that dependency for our team, and this is definitely out of scope for us.”

They were right. That’s the part worth writing about.

Why I built it in the first place

We were starting a TypeScript migration on top of openapi-typescript. It didn’t support TypeScript 6 yet, so I opened a pull request to add it.

The PR sat. Six weeks open. Someone offered $250 in sponsorship to get it merged. It’s still open today. The project isn’t abandoned, just slow, and “slow” was enough to block a migration with a deadline.

So, in spare evenings, I built my own: openapi-zod-ts, four packages that turn one OpenAPI spec into a fully-typed client, a server interface, React Query hooks, and Zod validation wired into the router. It already did more than the library it was meant to replace. If you want the architecture, that’s a separate deep dive. This post is about what happened when I brought it to work.

The no was fair

I introduced it as a candidate for the migration. The answer was no, for the reason quoted above: single maintainer, barely a week old, adopting it means adopting me.

I didn’t argue, because the objection is correct. The bus factor is one. The project was days old. If I get hit by a bus, or just get bored, the team owns a dependency nobody else understands. That’s a real cost, and pretending otherwise would be dishonest.

What I said back, once

Here’s the case I made anyway, and then dropped.

The existing libraries aren’t in a better position. hey-api is one or two people moving fast with frequent breaking changes. openapi-typescript has my TS 6 PR sitting unmerged with a $250 bounty on it. None of these is a well-funded, multi-org maintenance story. They’re individuals maintaining open source in their spare time, exactly like mine. “Single maintainer” isn’t the gap between my tool and a safe choice. It’s the baseline for the whole category.

And openapi-zod-ts is MIT licensed. If I stop maintaining it, the team forks it. That’s the entire point of the license. The output is readable TypeScript you own, not an opaque runtime you rent.

Then I stopped. I said: here’s the tool, here’s the comparison, you make the call. I’m not going to force it. Pushing a dependency onto a team that doesn’t want it is exactly how you become the single point of failure they were worried about.

So I made it undeniable instead

After the no, the team moved on. No review, no follow-up questions, no second conversation. Fair enough: I had made my case once, they had made their call, and I wasn’t going to relitigate it.

But I couldn’t leave the tool where it was. Not to change anyone’s mind, nobody was waiting for a sequel, just because I knew it wasn’t finished. A code generator has a wide blast radius: one subtle regression touches every project that runs it. If I was going to keep depending on this myself, it had to earn that trust. So I spent a few more evenings, not on features, but on quality.

A handful of evenings later, openapi-zod-ts had one:

• Near-100% test coverage across all four packages, enforced in CI. A PR that drops coverage fails.
• A 128-spec compatibility matrix. The generator runs against 128 real public specs, Stripe, GitHub, OpenAI, Adyen, Spotify, Twilio, and 120-plus more. 128/128 generate without errors on every PR.
• Smoke tests against live public APIs. The generated client fires real HTTP requests at real servers on every push to main, not just a “does it compile” check.
• Mutation testing with Stryker, which deliberately breaks the source to prove the tests actually catch regressions. High coverage that doesn’t catch bugs gets exposed here.
• A full-stack Playwright E2E. One spec drives a runnable petstore app, browser to server, and the whole round-trip runs on every PR.
• Static analysis on every PR via Fallow and CodeQL.

That’s the Why Quality Matters section of the repo now. Nobody asked for it. I wrote it because the alternative was shipping something I knew could break quietly, and I couldn’t live with that.

Then I went hunting for boilerplate

The other thing I couldn’t stop thinking about was how much hand-written code my dependency could delete. So I went looking for boilerplate to kill.

The generated React Query hooks were one source. Testing them meant writing the same QueryClient setup and manual mocks in every project that used them. So the generator now emits a test-utils.ts next to the hooks, every time, with zero new dependencies: a pre-configured test QueryClient and a wrapper for renderHook. A dozen lines of setup and hand-rolled mocks collapse to one.

Stack that across a whole API surface and it adds up. The proof-of-concept PR I put up cut the API-related code by about 50%. Half the hand-written client and test code, gone, replaced by generated output you can actually read.

What I actually got

A side project, built after hours. I didn’t get adoption, and after the first no the team didn’t spend another word on it. That’s their call, and I don’t push. Forcing a dependency onto people who don’t want it is how you become the single point of failure they were worried about in the first place.

What I got instead: a tool that does the job better than the library it would have replaced, an API layer that’s half the code, and the quiet satisfaction of finishing something properly when nobody asked me to. It’s MIT, it’s on GitHub, and the architecture is documented if you ever want it.

The PR that started all of this is still open upstream. I stopped waiting for it. I built something better instead.