[loloquhwonedeo]

It would be great if the API specification could be written once and then consumed by both server and clients, not only for functional validation as shown in the article but also for the server to use the spec to validate and serialize inputs/outputs.

As described, there is a disconnect where you went to all the work to create the openapi oas.yaml file, and can feed that to your test client to ensure the API responds to that, but the API still had to be coded by hand to comply with the spec.

A way to feed the oas.yaml code to flask-smorest somehow so it derives the endpoints and schemas from that (hey it already makes a ton of assumptions about how to structure the application, requiring e.g. a set of methods named exactly as the endpoints so they can be easily matched) would make it so the single oas.yaml file drives both ends of the implementation, would make coding work easier as the schema doesn't need to be described multiple times in multiple languages/formats, and would provide quick feedback (FAILURES) if I change the schema without coding the required endpoint support.

[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").

[Jtsummers]

CORBA kind of has you do that. You still have to add details for the implementation, but you write an interface description once and then both the client and the server know how to communicate. A code generator will produce that interface code, and can stub out the implementation part.

A lot of middleware systems do things like this. The critical part of what the author is doing is that they're spending time developing a specification. If you just grow it organically, on a larger project you're more likely to end up with a mess than a coherent system.