Seit Lektion 2.3.10 schreibt der Build das OpenAPI-Dokument der Kladde nach docs/api/Kladde.Web.json, und eine Prüfung im Workflow meldet,
wenn jemand vergessen hat, es mitzuschicken. Das Dokument war damit eine Beschreibung. In dieser Lektion wird es zum Vertrag: zu dem,
was die Kladde ihren Aufrufern verspricht. Ein Vertrag ändert sich nicht aus Versehen. Er ändert sich, weil jemand es will, ein anderer es
gelesen hat und beide wissen, ob ein Aufrufer etwas tun muss. Am Ende der Lektion liegt der Vertrag in openapi/kladde.json, ein Test wird
rot, sobald die API davon abweicht, und ein Client, den Sie gar nicht selbst geschrieben haben, spricht mit der Kladde.
Was „Vertrag zuerst“ heißt
Es gibt zwei Wege zu einem OpenAPI-Dokument:
- Code zuerst: Man schreibt die Endpunkte, und ein Werkzeug erzeugt das Dokument daraus. So macht es die Kladde seit Lektion 2.3.10.
- Vertrag zuerst: Man schreibt zuerst das Dokument, oft in YAML, stimmt es mit den Aufrufern ab und baut dann die Endpunkte dazu.
Vertrag zuerst ist der richtige Weg, wenn mehrere Teams gleichzeitig beginnen wollen oder wenn ein Partner den Vertrag unterschreiben soll, bevor es Code gibt. Für die Kladde ist er zu schwer: Zwei Dateien beschreiben dieselbe API, und irgendwann weichen sie voneinander ab.
Die Kladde nimmt einen Mittelweg, der den Kern von „Vertrag zuerst“ behält: Der Code erzeugt das Dokument, aber die eingecheckte Fassung
gilt. Weicht das erzeugte Dokument von der eingecheckten Fassung ab, ist das ein Fehler, bis jemand die Fassung bewusst ändert. So kann
niemand den Vertrag ändern, ohne dass es im Pull Request als Änderung an openapi/kladde.json steht.