This is exactly how FastAPI/Pydantic in the Python ecosystem works (and also in Django-ninja for Django).

You compose types representing your request and response shape. Those types validate the API request and it’s response, and also generate the OpenAPI.

Even slight drift between API spec, docs and actual behaviour is impossible in this setup, I couldn’t go back to working any other way!

Sure, though that goes against the API first design principles that OpenAPI seeks to enable. It also results in poorly documented, often garbled OpenAPI specs. Code-generated specs simply cease to be effective as contracts.

https://swagger.io/resources/articles/adopting-an-api-first-...

This is the best project I’ve found to that for that - https://github.com/lukeautry/tsoa. Uses decorators mainly.

If there are other such projects, please share.

This is something we hope to build relatively soon at Stainless, inspired by Stripe's in-house Ruby API DSL. I think what you're asking for is the right approach.