Very interesting idea, I'd love to see where it goes! This reminds me of Square's Racket DSL [1] for making OpenAPI tolerable, but perhaps a more pragmatic approach.
The team I worked with in my previous job built a lot of tooling around OpenAPI (CLI, GitHub integration etc.) to try and improve the developer UX around creating, maintaining, and collaborating on large definitions. The OAS definition for the company's core product amassed ~60k lines of YAML. Some of the features you listed happen to solve some of the biggest challenges we ran into:
> Type checks and autocomplete.
The CLI tool we developed was able to parse an OAS (expressed in a single file or over multiple ones using $refs) into a tree structure. This allowed the tool itself to reason about the state of the OAS, but it was difficult to expose the same information to the user via an editor extension or language server.
Utilising an existing language and all of its editor features to write the OAS to begin with would alleviate some of the pain points we saw when managing very large collections of OAS files.
> Easy CICD integration.
We built a whole GitHub integration that listens for webhook events (like PR opened, commit merged into master etc.) which then downloaded the OAS files from the affected repo, ran checks and validations, compiled them into a single monolithic file, uploaded the file to S3, and generated Markdown docs. I can imagine this process being much simpler if existing language tooling is leveraged.
> Git-friendly.
Definitely something to think about at scale.
> Live-reload preview though webpack-dev-server or similar.
We attempted a VSCode extension which ran the CLI tool in the background. It watched for file changes, attempted to parse them into a complete OAS definition, and then generated Markdown docs into a temp directory and invoked the Markdown Preview extension to display a live-reload preview. It worked most of the time, but using webpack-dev-server seems to be more fit-for-purpose. You would certainly have more flexibility in how the docs are generated; whether you want a basic Markdown to HTML rendering or throw the OAS into ReDoc or something.
Other aspects I reckon are worth thinking about:
- Contract-based testing. We added custom properties to our OAS files so teams could define test examples and scenarios in YAML. It was terrible to work with as YAML doesn't give you the amount of flexibility you need to define rich and varied test cases. I imagine this would be simpler in TS.
- Shared schemas and examples. You might have this in mind for the "Support for js modules and npm packages" feature, but a nice mechanism for defining and consuming shared schemas would be awesome. Maybe these could be published as NPM packages?
Some interesting points you raised:
> 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.
In my current job we use Goa [2] and its DSL to define the interface of the service. While the OAS it generates is not nearly as elegant as something that you could produce by hand, we've found it good enough to be viable as an artefact we immediately hand over to potential consumers of the service. We've had a lot of success working this way; consumers were able to use their own tooling to stand up mock servers to build against while we worked on our implementation.
The class of tools that generate OAS from code by attempting to map controllers or routes to operations and paths never work well.
[1] https://developer.squareup.com/blog/making-openapi-swagger-b...
[2] https://goa.design/