Prompt
Why I hate maintaining Swagger docs by hand
Latest observation
A lot of people do — and for good reasons.
Here’s why maintaining Swagger/OpenAPI docs by hand often feels awful:
-
It duplicates work
You’re already defining routes, request/response shapes, auth rules, and error cases in code. Rewriting all of that again in Swagger is extra maintenance with no real benefit. -
It drifts from reality fast
The API changes, but the docs don’t. Then the docs become misleading, which is worse than having no docs at all. -
It’s tedious and error-prone
Small changes like a renamed field, a new status code, or a slightly different schema mean touching multiple places manually. -
It breaks developer flow
Instead of building the API, you’re formatting YAML/JSON and keeping examples in sync. -
It encourages incomplete docs
When docs are a chore, teams tend to postpone them, skip edge cases, or document only the “happy path.” -
It’s hard to keep examples current
Example payloads, response codes, and auth requirements often become stale unless someone constantly babysits them. -
It creates ownership ambiguity
Is the spec owned by backend, frontend, QA, or technical writing? If no one clearly owns it, it rots.
The usual fix is to generate OpenAPI from code or use annotations/contracts close to the implementation, so the spec stays aligned with the actual API.
If you want, I can also help turn this into a:
- rant-style paragraph
- tweet/thread
- blog post intro
- bullet list for a presentation