When I was super green I argued about this with the principal engineer for quite a while about swagger.
Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
It depends on how you're party to that contract - whether you're involved in making it, or you're a consumer in a take-it-or-leave-it situation.
If I'm a consumer of some third-party API, there's no practical difference between intended behavior, accidental mutation and a bug which the supplier won't fix any time soon - all of these things are equally part of the contract of how The Thing v1.2.3 works, and that's what I want described in the documentation. Any part of the documentation that says what The Thing should do (but doesn't actually do) is worse than useless, it's actively misleading; it describes some wishful thinking with no connection to reality.
If the contract documentation describes an interface between two parts of the system that I control, and I have the ability to fix discrepancies between contract and code by altering the code, then sure, that's a different situation; but if I don't have the ability to make these changes because it's an API to code made, maintained and controlled by someone else, then accurately describing current reality is the most important thing.
You are mostly correct. However the contract can say "X in the API will change without notice so don't use it", which is valuable to know. Often there are things that must be exposed in the API for "reasons" but the user shouldn't use themselves.
Likewise if v1.2.3 has a bug I want to know to not rely on that because I'll probably update to 1.2.4 which fixes it.
I've also written a library to route into ktor in a type safe way.
But if you're doing swagger. To me it should be written, then consumed by the back-end service. Then generate front-end clients. Anything less will result in bugs.
I've seen companies pile on so many services. To double check code generated swagger. Hit a bug, then have to maintain the swagger spec outside and not enforce it.
> To me it should be written, then consumed by the back-end service.
This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it.
I've written a couple of libraries that do exactly this:
That's my mantra since 5 years now. Swaggerize-express or swole for the routing, but also swaggering-mongoose or objection's schema loaded from the yaml file for the database model. As a plus, validation is available out of the box.
You can add two new columns to your Kanban board called "Documentation" and "Documentation Review".
Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.
In addition to this (and going a bit off topic). I've been adding checklists to Github PR templates (it's really easy[1]) for things like, "Did you re-read the relevant API docs? Do they need to be changed?" and it helps me a ton.
Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?