4 ms·

I do the opposite and leave generating openapi docs to an LLM. Mostly that just involves spelling out the obvious; so it's not a particularly hard job for an LL

I do the opposite and leave generating openapi docs to an LLM. Mostly that just involves spelling out the obvious; so it's not a particularly hard job for an LLM. The code is the full specification of what a thing does. Anything else is just a watered down version of the thing. In architecture terms, there is no blue print for the blue print, typically. This is a fundamental misconception some people have about software design vs. traditional engineering/architecture. When designing buildings, you put all your effort in the blue print. And then you build it. With software, you put all your effort in the blue print (i.e. the source code). And then you run/compile it. In neither case is it valuable to have a meta blue print. At best you might do some sketching, prototyping, modeling. But these are activities intended to learn, not to document. 3D printing makes the metaphor more obvious maybe. Because it makes engineering more similar to software development. All the key work is digital.

dtkav 2y ago
I think you might have a fundamental misunderstanding about what OpenAPI specs are for. If you just need docs then maybe that works for you. OpenAPI can do so much more though - it can specify a protocol. If you can't see why a protocol specification is different from an implementation of that protocol then I don't know what to tell you.
- jillesvangurp 2y ago
  Most uses of OpenAPI I've seen is simple REST API documentation. Many internet standards & protocols are typically developed together with their reference implementation. E.g. the IETF is pretty good at that for things like HTTP. Waterfall just doesn't work for anything moderately complicated. If it's simple, a lot of upfront documentation is not going to be that helpful. If it's not, a proof of concept implementation that irons out all the design mistakes and that proves it is any good would be a good idea. There aren't a lot of good protocols that get developed without those. Anyway, the article is about slapping openapi specs on python web frameworks, which suggests it's being used in its usual role of documenting existing APIs here. And for REST protocols, python is a great tool to prototype those.

dtkav 2y ago

I think you might have a fundamental misunderstanding about what OpenAPI specs are for. If you just need docs then maybe that works for you. OpenAPI can do so much more though - it can specify a protocol. If you can't see why a protocol specification is different from an implementation of that protocol then I don't know what to tell you.

jillesvangurp 2y ago
Most uses of OpenAPI I've seen is simple REST API documentation. Many internet standards & protocols are typically developed together with their reference implementation. E.g. the IETF is pretty good at that for things like HTTP. Waterfall just doesn't work for anything moderately complicated. If it's simple, a lot of upfront documentation is not going to be that helpful. If it's not, a proof of concept implementation that irons out all the design mistakes and that proves it is any good would be a good idea. There aren't a lot of good protocols that get developed without those. Anyway, the article is about slapping openapi specs on python web frameworks, which suggests it's being used in its usual role of documenting existing APIs here. And for REST protocols, python is a great tool to prototype those.