Editors

The API design editor is where governance actually meets the human being doing the work, and that’s why I’ve cared about editors for as long as I’ve cared about API design. An editor is the tool where a developer or designer creates and edits an API definition — the OpenAPI or AsyncAPI contract — and it’s the single most important place to inject governance, because it’s where the decisions get made. You can run all the linting you want in the CI/CD pipeline, but by the time a violation is caught in the pipeline, the developer has already moved on, already made the mistake, already built around it. The editor is where you can catch the problem at the moment of authorship, while the person is still thinking about it and can still cheaply change it. I’ve spent more than a decade wishing for, evaluating, and eventually helping build the kind of editor that makes governance a real-time, inline, helpful part of designing an API rather than an after-the-fact audit.

My obsession with the ideal editor goes back to 2014, when I wrote about what my perfect API design editor would look like. My wishlist even then wasn’t just about editing YAML — it was about an environment that helped you get started with patterns, that managed a gallery of reusable designs, that integrated with the rest of the lifecycle, that made good design the path of least resistance. The next year I expanded the vision toward building it on Electron, imagining an extensible, API-driven design environment. What I was reaching for, before I had the vocabulary for it, was an editor that didn’t just let you write a definition but actively guided you toward a good one. That guidance idea — the editor as a teacher and a guardrail, not just a text box — is the thread that runs all the way from 2014 to the governance editors I’m excited about now.

The format wars shaped the first generation of API design editors, and I covered them closely. By late 2014 I wrote that there were four API design editors to choose from, reflecting the competition between Swagger, RAML, and API Blueprint and the tools each ecosystem produced. The Swagger Editor was a genuine leveling event — when Swagger shipped its editor with YAML support in 2014, it leveled the API design playing field, making it possible for anyone to write an API definition in a clean, readable format with live validation right there in the browser. That browser-based, validate-as-you-type experience was the seed of everything that followed. Apiary, built around API Blueprint, was the pioneer of the design-first, mock-as-you-go experience — I was writing about easy API development with Apiary as early as 2011, and it expanded a lot of designers’ horizons about what design-first could mean before Oracle acquired it in 2017. RAML had its own strong tooling. The format competition was sometimes tribal and exhausting, but it drove rapid innovation in the editor experience, and OpenAPI’s eventual consolidation of the space inherited the best ideas from all of them.

The open-source visual editor was the thing I wanted most and waited longest for, and I was vocal about the gap. I kept arguing that a common open-source API design editor was needed across all the API service providers — that the proprietary, locked-in design tools were holding the space back, and that we needed a shared, open foundation everyone could build on. I literally published requests asking someone to please develop an embeddable, open-source, visual API editor. When Apicurio arrived in 2017, I wrote that it was the open-source visual API design editor I had been looking for — a genuinely open, GitHub-integrated, visual environment for designing OpenAPI. Stoplight was doing important work too; I took a close look at the Stoplight spec editor in 2017, and their “automagically define your infrastructure as you work” approach was pointing at the same future. But the open-source piece mattered to me specifically because design tooling is foundational infrastructure, and foundational infrastructure shouldn’t be entirely owned by vendors. I kept hoping, as late as 2019, for more investment in API design tooling, because I felt the space was perpetually under-resourced relative to its importance.

The editor as a stabilizing force is something I learned from my own practice, and it changed how I thought about the tool. I wrote in 2018 that working with my OpenAPI definitions in an actual API editor helped stabilize them — that the act of loading a definition into a proper editor, with its validation and structure and visual representation, surfaced inconsistencies and errors I couldn’t see when the definition was just text in a file. The editor isn’t a passive container; it’s an active participant in producing quality. A good editor makes the structure of your API visible, flags what’s malformed, and nudges you toward consistency just by rendering your work in a way that makes problems apparent. That experiential insight — that the right editor materially improves the definitions you produce — is the practical foundation under the governance-editor vision.

The governance editor is where all of this has converged in the last few years, and it’s genuinely the realization of the thing I’d been describing since 2014. The breakthrough was combining a real code editor — specifically Monaco, the editor that powers VS Code — with governance rules, so that Spectral linting, design-guide checks, and inline guidance run live as you type. I wrote in 2024 about using the Monaco editor to govern and guide API artifact changes, and through 2025 about building a baseline of Spectral rules with guidance directly in Monaco, about inline guidance for OpenAPI in a simple governance editor, about IntelliSense-style hints for governance. This is the editor I always wanted: one where the governance isn’t a separate audit step but is woven into the authoring experience itself — IntelliSense hints, real-time rule feedback, inline explanations of why a pattern is discouraged and what to do instead. The OpenAPI Doctor, which I called what API innovation looks like in 2025, embodies this: an editor that diagnoses your OpenAPI against governance rules and gives you a health check as you change it, tough but worth it. The governance moved from the pipeline, where it nags, to the editor, where it teaches.

The design principles I’ve landed on for the modern editor are about making it accessible and shareable, not just powerful. I described the editor I want as snackable, shareable, forkable, embeddable, with both visual and source modes — because the editor shouldn’t be a heavyweight application you have to install and learn, it should be a lightweight thing you can drop into a documentation page, share a link to, fork like a GitHub repo, and use either visually or in raw source depending on your preference. The dual visual-and-source mode matters because different people and different moments call for different views: sometimes you want the form-based, guided, visual experience, and sometimes you want to be in the raw YAML with full control. The best editor serves both without forcing a choice. And it should be embeddable, so that governance-aware editing can live wherever API work happens rather than being confined to one vendor’s walled application.

The frontier now is the editor merging with the IDE and AI, and this is where governance-in-the-editor becomes genuinely powerful. I wrote in 2025 that developers will listen when API governance is injected into the IDE via AI — because the place developers actually work is their IDE and increasingly their AI coding assistant, and that’s where governance guidance needs to live to be heard. The CLAUDE.md and copilot-instructions.md family of files, the AI assistant that knows your design standards, the governance rules surfaced as the developer types in their real working environment — this is the editor vision extended into the agentic era. The editor was always about meeting the human at the moment of creation with helpful guidance. As that moment of creation moves into AI-assisted workflows, the editor’s governance role moves with it. The throughline across twelve years is constant: the editor is the highest-leverage place to make good API design easy and bad API design hard, because it’s where the work actually happens. Governance that lives in the editor gets followed. Governance that lives in a document nobody reads, or a pipeline that catches problems too late, does not. The editor is where governance becomes real.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Editors

References

Guidance Details

Explore more

Discover APIs