A public API's documentation says the `POST /matches/{id}/scorecards` endpoint accepts an `overs` field as an integer. The actual server, three releases later, expects a decimal — `19.4` meaning 19 overs and 4 balls — because a developer fixed a real bug without anyone updating the prose description sitting in a separate docs site nobody on the API team maintains day to day. A third-party developer reads the published documentation, builds an integration exactly to what it says, and every request fails validation in a way the documentation gives no hint of, because the documentation was never actually checked against what the server does — it was only ever checked against what the server did once, a long time ago.
A machine-readable OpenAPI document closes that gap by being the one artifact both the server's behavior and every description of it can be generated from or validated against, rather than two independently maintained descriptions of the same API that are free to drift apart the moment one of them changes without the other. Treated as the source of truth, the OpenAPI document isn't documentation the team also happens to publish — it's the actual contract the server is built to honor, the client SDKs are generated from, the mock server for testing is built from, and the human-readable reference is rendered from, all pointing back to one file instead of four independently maintained ones.
Analogy🏏Cricket
🏏 Think of it like cricket: During any international match, exactly one scorebook is the official record — kept by the appointed scorers sitting with the match officials, ball by ball, and every other version of the game's numbers that reaches the public has to trace back to it. The stadium's giant screen, the broadcaster's on-screen graphics, a fan's second-screen app, and the newspaper report filed that evening are all just different presentations of that one official record, not four independent tallies that happen to usually agree. If the broadcast graphics team kept its own separate count instead of pulling from the official scorers, a mis-keyed entry on the graphics side would show the wrong score to millions of viewers while the actual match, and every other correctly-sourced feed, stayed right — a disagreement with no way to resolve it except asking which of the four independent counts to trust. Just as the official scorebook is the one record every other presentation of the match has to derive from, an OpenAPI document is the one contract every client, mock, and reference page has to derive from. Just as a broadcast graphic that drifts from the official scorebook is wrong precisely because it stopped deriving from the single source, documentation that drifts from what the server actually does is wrong precisely because it was maintained as its own independent description instead of generated from the one contract the server is built against. The insight is that having one authoritative source and deriving everything else from it is what makes 'which version is correct' a question that never needs asking.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.