Since lesson 2.3.10, the build writes the Kladde's OpenAPI document to docs/api/Kladde.Web.json, and a check in the workflow reports when
somebody forgot to include it. That made the document a description. In this lesson it becomes the contract: what the Kladde promises
its callers. A contract doesn't change by accident. It changes because somebody wants it to, somebody else has read it, and both know
whether a caller has to do something. At the end of the lesson, the contract lives in openapi/kladde.json, a test turns red as soon as
the API deviates from it, and a client that you didn't write yourself talks to the Kladde.
What "contract first" means
There are two ways to an OpenAPI document:
- Code first: you write the endpoints, and a tool generates the document from them. That is how the Kladde has done it since lesson 2.3.10.
- Contract first: you write the document first, often in YAML, agree on it with the callers, and then build the endpoints to match.
Contract first is the right way when several teams want to start at the same time or when a partner is supposed to sign the contract before there is any code. For the Kladde it is too heavy: two files describe the same API, and at some point they drift apart.
The Kladde takes a middle way that keeps the core of "contract first": the code generates the document, but the checked-in version
counts. If the generated document deviates from the checked-in version, that is an error until somebody changes the version on purpose.
That way, nobody can change the contract without it showing up in the pull request as a change to openapi/kladde.json.