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.…