I absolutely hate writing Open API documents in yaml by hand. GUI tools like StopLight Studio are a bit better, but still don't really cut it for me.

I don't like generating it from code either because it tends to clutter everything and devs usually get too confident and don't bother to make sure that the output is good enough.

So, ever since I saw the aws-cdk I can't stop thinking that this approach would be a perfect solution for generating Open API docs in a much more dev-friendly way.

Here's a list of features that either would work out of the box or with just a bit of effort:

- Language bindings for popular languages through jsii (https://github.com/aws/jsii) (same tech behind aws-cdk).

- Type checks and autocomplete.

- I18n.

- Support for js modules and npm packages.

- Easy CICD integration.

- Git-friendly.

- Live-reload preview though webpack-dev-server or similar.

I've been working on a very rough and unfinished POC. This is how it could look like:

https://github.com/marcmarcet/openapi-cdk/blob/main/packages/demo/bin/app.ts

Do you guys think this makes sense? do you see it getting any interest from the community?