It was a Monday morning. A partner pinged us because their integration had broken overnight. Turns out, someone had merged a PR that renamed a response field from user_id to userId — camelCase instead of snake_case, a two-character diff — and the OpenAPI spec had not been updated. The spec said one thing. The API did another. The partner built against the spec.
That's spec drift. And if you've maintained a non-trivial API, you've been bitten by it.
The standard advice is "keep your docs close to your code." Put the OpenAPI YAML in the same repo. Add a linter to CI. Write a custom rule that fails the build if the spec is missing a path. This helps. It doesn't fix the underlying problem, which is that you're maintaining two sources of truth — the code and the spec — and hoping they stay in sync.
The real fix is to have only one source of truth.
The idea isn't new. For years, certain frameworks have offered a path here. If you're on NestJS, you can use @nestia or the built-in Swagger plugin and get spec generation from TypeScript types and decorators. If you're using FastAPI, you get it for free — the spec is generated from your Pydantic models and route definitions at runtime. If you're on tsoa, you write TypeScript classes with decorators and the spec is a build artifact.
The pattern is the same in all of them: the spec becomes a consequence of the code, not a parallel document you maintain by hand. When you rename a field in code, the spec updates automatically on next build. Drift becomes structurally impossible.
The problem is that this only works if you're already on one of those frameworks. If you have an Express app written without decorators, a Go service using chi or gin, a Fastapi app where someone skipped the Pydantic models for "simplicity," you're back to hand-maintenance.
What actually needs to happen for those cases is static analysis of the routes: parse the AST, find the route definitions, infer the request and response shapes from the types that flow through them, extract any JSDoc that's already there, and produce a spec that reflects what the code actually does.
This is what I've been building. It's called DocSmith. You point it at a repo, it scans the route definitions, and it produces an OpenAPI spec from the code — no decorators required, no framework lock-in. It currently understands Express (TypeScript and plain JS) and FastAPI, with more frameworks on the roadmap.
It's at demo and waitlist stage right now, not generally available. I want to be upfront about that — there's a live demo at docsmith-app.launchyard.app where you can see what the output looks like, and a waitlist if it seems useful to you. I'm not going to oversell where it is.
What I'm trying to figure out right now: what framework are you maintaining API docs for, and what's your current approach? Manual YAML? Postman collections? A decorator-based framework that handles it automatically? Something I haven't thought of?
Genuinely curious what's actually working for people — drop it in the comments.
Top comments (0)