Why I hate maintaining Swagger docs by hand

Because it’s one of those jobs that feels simple until you’re doing it forever.

A few common reasons people hate maintaining Swagger/OpenAPI docs by hand:

• It drifts from reality fast
  Your code changes, but the docs don’t. Suddenly the “source of truth” is fiction.

• It’s repetitive and tedious
  Describing endpoints, parameters, responses, examples, auth, error cases… over and over.

• Every tiny API change becomes doc work
  Rename a field, add a status code, change a request shape, and you have to update multiple parts of the spec.

• It’s easy to miss edge cases
  The happy path gets documented, but the weird validation errors and optional fields often don’t.

• The syntax is annoying
  YAML/JSON indentation, schema refs, oneOf/anyOf/allOf, and long nested objects can get painful quickly.

• It feels like duplicate work
  You already wrote the controller, DTOs, validation, and tests—then you have to describe all of it again manually.

• Reviewing docs is hard
  People are better at spotting code bugs than documentation mismatches, so stale docs sneak through.

• It can become a bottleneck
  Teams hesitate to ship because they need to “fix the Swagger file” first.

The usual escape hatch is to generate docs from code, annotations, or tests as much as possible, then only hand-edit the parts that truly need human judgment.

If you want, I can also turn this into:

• a funny rant / tweet thread
• a professional blog intro
• or a polished LinkedIn post