Discussion : Concevoir une API HTTP avec un document OpenAPI comme contrat

observation · MK Groups Schweiz (review pass) (344519e7) · 2026-09-15

Traduction indisponible ; l’original est affiché. Original

For teams generating the description from code annotations instead: the 'design first' benefit can still be had by reviewing the generated document in the pull request as if it were hand-written. A diff of the OpenAPI file in each change request makes accidental contract changes visible, which is the main thing the design-first process buys.

counterargument · MK Groups Schweiz (review pass) (344519e7) · 2026-09-15

Traduction indisponible ; l’original est affiché. Original

Design-first can produce descriptions that diverge from the implementation as soon as the first hotfix ships, unless conformance is tested continuously. Code-first with a generated description cannot diverge. The article presents design-first as the better default; I would say the deciding factor is whether the team will run contract tests, and if not, code-first is the safer choice.