Vibe-engineering an OpenAPI compatible API authoring tool
As an engineering lead, I spent most of my time architecting systems, writing issues, and translating business requirements into clean technical requirements which involve some form of API documentation and authoring DTOs.
Defining the API as a contract before implementing it helps the frontend and backend teams start work in-parallel instead of one waiting for another to get their types and flow of the APIs.
The OpenAPI Initiative happens to create a specification that is very powerful for documenting APIs allowing developers to write clear, defensible API contracts that act as a single-source-of-truth for backend engineers, frontend engineers, QA, technical leadership, and now even AI agents.
There are primarily two ways you could create an OpenAPI-spec compliant API Documentation:
You either hand-author YAML files or rely on code-first generation with the backend framework of your choice. Both are absolutely valid approaches that I’ve seen teams use but both approaches suffer from very different problems.
Editing YAML files by hand is, frankly, not an intuitive way to design what APIs should accept and respond. As the API-surface gets bigger, so does the cognitive cost of keeping up with this increasingly large YAML file. Despite being designed to be a more “human-friendly” alternative to JSON, YAML is still hostile to humans and troublesome to write and maintain.
This “barrier” of authoring YAML files is problematic enough that I see teams avoid writing OpenAPI because of this. Oftentimes, I’ve preferred writing markdown files with embedded Typescript code blocks for defining API contracts and request/response schemas simply because it was much easier to do.
A much more reasonable, alternative approach some teams use is code-first generation. Frameworks like FastAPI have first-class support for automated OpenAPI generation as you write routes and request/response models. Other popular frameworks like Gin, NestJS also have complementary packages that does the job insanely well.
But this approach has its own set of problems:
Your backend engineers are now in charge of the API contract. It can, and it will deviate from what you initially proposed.
On several occasions, you will have to fight the framework to ensure that you get the auto-generated documentation right. This can sometimes be in the form of messy boilerplate, or ugly hacks to show a particular type in the spec and remain compatible with code-generation.
This may not be such a dealbreaker for small teams that move fast and do not consider contract-led development important. In fact, if you are able to deal with these two potential issues: the upsides are great. These auto-generated specs are a great way to guarantee end-to-end type-safety between your API clients.
Still, the fact remains that code-first generators see API contracts and documentation as an afterthought. A side-effect of well-written backend code.
Existing Solutions
Are you saying that this is a problem that people haven’t tried solving? Of course not. There are dozens of tools available online that you could use. Even Smartbear (the folks behind OAS) themselves have created the official Swagger Editor, which is YAML-first but not very intuitive unless you get comfortable with the editor. There is Stoplight, which is heavy, and enterprise-first, and has a pricing page! Sure, you could use Postman which works but very clearly isn’t designed for OpenAPI-documentation despite supporting it.
I just want a super-simple, preferably open-source, and free to use API documentation tool. I don’t need accounts, cloud sync, onboarding, pricing, and all that crap!. Is it too much to ask for?
The project closest to what I was looking for, which I found on Github was a little tool called openapi-gui which is quite nice and supported the functionality I was looking for. However, it hasn’t been maintained in over three years and hasn’t evolved with the latest additions to the OpenAPI specification.
Unless…
“I could probably build that” - every engineer ever
Having worked with OpenAPI specifications extensively for the past couple of years and with the power of agentic engineering. I figured; I should probably give it a shot and build something that solves the pain points I’ve highlighted. An intuitive, clean, and simple GUI tool that lets me author API contracts, with support for serializing them into the OAS-YAML files.
I took the assistance of v0.dev and Github Copilot to scaffold a new project. I didn’t want to “vibe-code” it because OpenAPI itself is a complex spec, and being an engineer, it irks me to fire off a dozen mindless proompts and hit save on some AI-slop, no, no, not on my watch you don’t.
I was going to vibe-engineer this project. Starting off with a detailed plan and architecture, fully human-in-the-loop workflow. The agent was still writing 90% of the code but I would occasionally go in and make changes to minor things that I could do much faster than the agent because a prompt → think → execute → review → accept cycle to change the color of a button is how you slowly develop AI-induced brain rot.
The plan
What I did not intend to build: An OpenAPI YAML editor or a Swagger UI clone.
I didn’t want this tool to be YAML-first but instead have its own internal canonical model. This felt like a good-enough abstraction that allows the tool to be independent of OAS and potentially work with any such specification in the future. It also opens room for extensibility beyond the scope of the spec.
Another important consideration was speed and offline-mode. Being a sucker for performance, I wanted it to be blazingly fast. The OpenAPI YAML files I often work with are easily 10k+ LOC. I didn’t want to build a tool that would crawl to process such huge files.
Instead of editing YAML directly, the spec is represented as a typed, in-memory graph. Schemas, routes, parameters, and responses are all nodes with stable IDs. References between them are typed edges, not $ref strings.
This means:
You can’t create broken references. Edges must point to real nodes.
O(1)to find “where is this schema used?”Circular references and invalid relationships are detectable in real time
Internally, the editor stores the entire API surface as interconnected Map<NodeId, Node> collections. Editing a schema or route is just a direct mutation of this graph.
This allows YAML to only exist at the boundaries (import/export) as a serialization/deserialization layer. This approach offers better performance on large files, off-spec features for QOL (grouping, colors, validators) without polluting the output, and simple undo/redo via graph snapshots.
And here is the final product! My recent obsession with neo-brutalist interfaces did make its way into this little tool as well 😅
A future beyond OpenAPI?
While I tried to support the majority of features outlined in the OpenAPI spec, there are still some things left out such as support for callbacks/webhooks. But I’m very satisfied with what a few hours of agentic engineering could achieve, and I feel like adding support will be a trivial task. As I was developing this editor though, I had some very interesting ideas beyond just being a GUI-based OpenAPI editor.
Because OAS allows someone to author a very detailed outline of an API surface, it is an excellent source for deterministic code-generation (into validators like zod/class-validator, models like pydantic, etc.) as well as a context-rich documentation for LLMs. A step in this direction will take this from an API authoring tool to a really powerful high-level architecting space for people doing spec-driven development using AI agents. There’s a lot of potential there!
If you’ve read this far, try it out for yourself! You can also find the repository here.
If you’re doing hobby projects or your entire pipeline is pure code-gen and you’re doing fine, you’re better off and probably faster sticking with that approach. But if you’re a tech lead or a backend engineer who cares about contract-led development. I hope that this tool might actually be useful!