As we step into the next era of Swagger Editor, we're excited to reveal the technology and features driving it under the hood. Designed to deliver a powerful and flexible developer experience entirely within the browser, the new editor represents a significant leap forward. In this post, we'll delve into the core architecture, highlight key features such as integrated language services and extensive customization capabilities, and show how these advancements can help you build, validate, and extend your API projects with confidence.
Why a New Editor?
Swagger Editor has been a trusted tool for API designers since its original launch in 2014. After years of evolving alongside the API landscape, we’ve learned countless lessons along the way. Now, three years since the start of its development, we’re proud to introduce a next-gen solution that builds upon this foundation. The new Swagger Editor addresses today’s demands head-on, supporting multiple API specification standards and adapting as they evolve, providing a smooth editing experience with instantaneous feedback, and remaining fully extensible so users can customize their experience and features to match their workflows.
Core Features
Swagger Editor provides several enhancements for flexible API design experience:
- Monaco Editor Foundation: The new editor builds upon the same codebase as Visual Studio Code, enabling fast editing, Language Server Protocol integration and scalable interface.
- Advanced Language Server Protocol Capabilities: The Editor delivers real-time validation, context-aware auto-completion, go-to-definition, syntax highlighting, and documentation directly in the browser for a streamlined experience.
- Multi-specification Support – Out-of-the-box compatibility with OpenAPI 2.0, 3.0.x, 3.1.0 and AsyncAPI 2.x ensures support for the industry’s most widely used API description formats, with more on the way, including AsyncAPI 3.0.
- Extensible Plugin System – Users and contributors can seamlessly integrate custom plugins to customize the editor’s UI, adding new features or adapting them to fit their needs.
Technology Stack
Under the hood, Swagger Editor is composed of several key technologies, working together to deliver a responsive and extensible editing platform:
- Monaco Editor provides a rich editing interface with robust support for advanced features and a strong, established ecosystem.
- Swagger ApiDOM serves as the data layer, parsing various specification formats into a unified structure for describing APIs. This unified layer powers multi-specification support, including OpenAPI, AsyncAPI, and any future formats, and provides the foundation of Language Server Protocol capabilities, which are integrated within Monaco Editor.
- Modular Plugin System enables easy enhancements to the Editor without modifying the core code. The provided plugins interact with the Editor state using Redux, opening the door for advanced integrations and customizations.
Language Server Protocol in Action
A defining feature of the new Swagger Editor is its deep integration with the Language Server Protocol (LSP). LSP enables the editor to provide advanced, language-aware capabilities for API specifications, such as:
- Real-time Validation: Instantly flag errors in your API definitions, catching mistakes as you type.
- Autocompletion: Speed up editing and reduce mistakes by suggesting references and property names derived from the API specifications.
- Go-to-definition and Definition Preview: Hover over the reference to see its definition and effortlessly jump to where the referenced schema, parameter or other element is defined, eliminating the need for manual searching through large documents.
- Syntax Highlighting and Inline Documentation: Quickly distinguish different parts of your API and easily access contextual documentation by simply hovering over a term.
For example, as you define a new operation, LSP will suggest required fields, validate data types, and ensure references are correctly resolved. This makes specification files easier to write and maintain, especially as APIs grow in size and complexity. All these capabilities are delivered directly in Swagger Editor, without the need for additional configuration.
Customizing Your Experience
Swagger Editor’s plugin system empowers you to tailor the editing experience to your needs. Plugins aren’t limited to background tasks – they can alter the user interface, hook into the rendering pipeline, or integrate third-party tools, bringing in new features. The capabilities of Monaco Editor can also be extended by using Visual Studio Code API to register custom extensions or providers, adding new behaviors on predefined events or customizing the context menu options.
For those familiar with adding custom plugins to Swagger UI, Swagger Editor customization process will feel instantly approachable, as it is built on top of the Swagger UI system. You can also pick and choose from the default plugins provided by Swagger Editor and integrate them with Swagger UI, scaling the experience to your needs.
Beyond the built-in LSP features, you can extend the language services with your own validation rules tailored to your needs. For example, suppose your APIs must always include contact information or enforce certain parameter naming conventions. You can register custom LSP rules that detect these issues and provide immediate feedback.
Developers can start by consulting Swagger Editor’s LSP plugin documentation and the ApiDOM Language Service guide, which detail how to write and contribute custom rule sets. This modular approach means your style and compliance rules live outside of the core logic, keeping upgrades straightforward and maintenance low-effort.
Community and Contribution
The Swagger Editor’s strength comes from its community. The project is open source, and we actively encourage feedback, feature requests, and pull requests for improvements and new features. You can find the Swagger Editor repository, read the contribution guide, and get involved with our initiatives today.
Looking Ahead
With its modern tech stack and extensible core, Swagger Editor is built to last. We are continually looking to improve performance for larger specs, expand support for new standards, and introduce features for a greater editing experience. As the API landscape evolves, so too will the Editor, adapting to new technologies, industry requirements, and community feedback.