I stopped manually maintaining OpenAPI specs — here's what I did instead

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