I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and documentation. What will often happen is I'll start writing down the documentation for a prototype and it'll be so full of awkward preconditions or poor ergonomics that I will realise where I need to make improvements.<p>Regarding this particular example, the API specification is not what I would call documentation since it leaves the reader to guess most of what is going on. A todo service is trivial, but maybe if it had more explanation the author would have spotted the stray 'priority' in the first version of the schema...
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.<p>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.<p>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.
Funnily enough, I'm trying this right now with a personal project using JSON Schema and quicktype [0]. It's phenomenal how it's nudged me to really think about the boundaries between components, and I get type-safe serialization code generated for free!<p>[0] <a href="https://github.com/quicktype/quicktype" rel="nofollow">https://github.com/quicktype/quicktype</a>
A lot (although not all) of the advantages of the method given here are also advantages conferred by something strongly-typed like ASP.NET; quite a bit of the testing in the post seems to be there solely to make up for the fact that you can't specify the type of your output up front.
IMO something like Apiary [1] and running the blueprint as a mock server is even easier.<p>[1] <a href="https://apiary.io/how-apiary-works" rel="nofollow">https://apiary.io/how-apiary-works</a>