this post was submitted on 11 Feb 2026
-3 points (36.4% liked)
Programming
25463 readers
302 users here now
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Regardless of what the author says about AI, they are bang on with this point:
A previous project I worked on we had a manually maintained Swagger document, which was the source of truth for the API, and kept in sync with the code. However no one kept it in sync, except for when I reminded them to do so.
Based on that and other past experiences, I think it's easier for the code to be the source of truth, and use that to generate your API documentation.
You can also use the OpenAPI generator to turn a well-formed Swagger document into code. I've used it before. I didn't hate it.
The generated controllers have a lot of boilerplate (I want to say 5 classes per controller), but it does guarantee the code is in sync with the documentation.
That being said, fuck manually maintaining swagger documents. It's the worst of all possible works.
There are solutions to this like having a doc comment right next to the function which is picked up by some API generator. Then it's easier to keep in sync. That can work well even in languages without explicit parameter types.
Of course it won't help LLMs as much, but I personally don't mind that.
I get there are some exceptions where devs don't have access to the docs, but I read this more like "Every time I update the code, I have to remember to update the description. I won't." Which, fair, but that's the author's problem. Writing docs is part of the job, table stakes stuff.
I mostly agree with your statement and I'm just nitpicking, but that document is not a source of truth if it has to be updated after the fact, it's a reference.