How do you keep an OpenAPI spec from lying about your API, and what's the real difference between a schema diff and a consumer-driven contract?

A code-first spec (springdoc generating /v3/api-docs from your controllers and DTOs) is never stale, but it's only as honest as what the code declares — error responses, headers, and examples don't get inferred, so leaving them out produces a technically-accurate-but-useless document. openapi-diff/oasdiff in the pipeline compares the spec on main against the branch and fails on a breaking change — the cheapest contract test there is, and it catches renames the author thought were purely internal. What it can't tell you is who actually reads which field: a consumer-driven contract (Pact) has each real consumer record the requests it makes and the fields it uses, and the provider's build replays those against the live service — a spec diff only knows the document changed, not whether it broke anyone.