API Documentation with Swagger/OpenAPI

Every API has documentation. The only question is where it lives and how long it has been wrong. A Word file on a network share, a wiki page, a Postman collection exported by a developer who has since left, a discussion thread where someone finally wrote down the example that works: these are the four forms it spontaneously takes, and they all share the same flaw. They are written alongside the code, so they diverge from the code with the very next commit.

The cost of that divergence is paid by others. A mobile app developer who sends a field that was renamed last week gets a 400 they don't understand, writes a message, waits for an answer, and loses half a day. Multiply that by the number of clients and the pace of change.

OpenAPI offers a structural answer rather than a disciplinary one: the API description is produced from the code itself. Paths come from the @RequestMapping annotations, schemas from the DTOs, constraints from the validation annotations. Renaming a field changes the documentation in the same commit, without anyone having to think about it. What remains to be written by hand are the intentions — what an endpoint does, why it can fail, what the client must send — that is, precisely what the code cannot infer.