[solumos]

In my opinion, this is one of the weakest points of spec-heavy approaches. These kinds of tools/approaches work great the first time you use them, but end up adding a lot of friction long-term. Or even immediately if that initial spec has to be re-done when requirements change just before implementation ships.

Although having a consolidated OpenAPI spec is miles ahead of plaintext documents in GDrive/DropBox, it feels like we could do so much more by using documentation to directly align and inform systems as they evolve (not just "at rest").