Developing the Swagger Editor: Lessons Learned
Swagger has become the standard for defining APIs in JSON with a huge community and a diverse set of tools. Apigee began to contribute to the tooling during the working group's definition of the 2.0 of Swagger specification. We embraced JSON Schema for validation and particularly invested in the API design-first workflows that a YAML-based format for editing enables.
Stage 1: Developing the editor PoC for Swagger 1.2
In order to enable the design-first approach, the concept of using YAML as an authoring format needed to be proven first. To do this, the Swagger Editor was built from scratch as a way to explore that kind of interaction. We began development before version 2.0 of the specifications was finished in order to prove the concept and requirements for the new workflows. The goal was to create an experience where designing an API was easy and fun.
We started with version 1.2 of the Swagger format, and, initially, the editor enabled users to write either JSON or YAML to define their specifications. We chose AngularJS as our main application framework and then added the Swagger UI library for rendering the documents in the preview panel. We also used Ace Editor, an open source online code editor.
After putting all the pieces together, we had a fully working editor that enabled you to edit Swagger specifications in YAML or JSON, and it could show your documentation right away in the preview panel. It also enabled you to download the JSON specification and use it in your favorite tool.
Wordnik provided an API for Swagger's code-generating server and client SDKs in different frameworks and languages. Users could edit the Swagger specification of their API and click a button to get SDKs for mobile platforms such as iOS and Android or get fully working servers in languages like Node.js and Java.
Phase 2: Aligning with the new 2.0 spec
After years of serving the API development community very well, the Swagger description format needed an overhaul. We worked with the Swagger working group to bring our deep experience with API descriptions into the next version of the Swagger API specification standard. Version 2.0 of the spec uses JSON Schema to define the structure of Swagger documents, making it easier to validate.
While the latest version of the specification was still under discussion in the working group, we started developing the Swagger Editor for version 2.0 before it was final. By having a real consumer of the new spec, we were able to make a lot of improvements and fix bugs. However, this also meant a lot of thrashing, as working with a moving target meant everything broke a lot.
For version 2.0, we took what we had learned about performance from the proof-of-concept iteration. This led us to ditch the Backbone.js-based Swagger UI and rewrite it with AngularJS. This helped us make a more streamlined project with fewer dependencies. It also helped the app respond more quickly to changes made in the Swagger document in real-time. We focused the editor on a YAML-only experience, as it kept the requirements simpler and allowed us to iterate faster. Longer term, we'd love to re-introduce JSON-editing back into the tool. One of the great wins came from the community-driven schema for the Swagger 2.0 specification. This made it possible to spot errors in the document using validators.
To make it easy to author API specifications in Swagger, we needed a better way of navigating inside the code structure. For instance, wouldn't it be awesome if users could see the generated documentation as a means of navigation and jump directly to the relevant section in the YAML? Or to give another example, when a user folds an operation, we can fold that section of the code in the editor to move those lines of code out of the user's way.
Having a link from generated documentation to jump to a line of code related to that documentation really helps, as does a link to a particular line of code related to a reported error.
Because of the structure of the app and the way we process user input, those requirements presented real technical challenges. For instance, this is how YAML is processed internally:
The annotator module annotates the Swagger JSON to provide information about lines of code regarding each node in the document. This helps us provide links to a line of code for each operator and path. The annotations also help us to reflect code fold changes in the editor within the generated document, and vise versa. We’re now parsing an Abstract Syntax Tree (AST) out of the YAML to enable adding even more annotations to the YAML document for better code navigation and other interesting use cases.
Apigee-127 and Swagger Editor
In parallel, we were developing the Apigee-127 project. It's aim was to give a better way to develop and publish APIs. Key to the experience was the idea that one should begin with API design and a specification-driven approach. This meant that from early on, another team was putting the Swagger Editor through its paces to solve real-world problems. In my experience, any time two teams' initiatives get aligned in this way, great things happen.
What does the Swagger Editor suggest about Swagger-UI?
The more work that went into the editor, the more it became obvious that the Swagger Editor and Swagger-UI projects would eventually need to merge. The wins that come from using Angular and all the cool things you can do with an abstract syntax tree suggest more cool things that can happen on the UI-side.
The road ahead
We’re still working on developing version 2.0 of the editor; we’re planning to add a lot of interesting and useful features to it. Here are a few:
Feature-parity with Swagger-UI and the merging of the two projects
Enabling users to test their API endpoints and operations right in the editor, without having to leave the editing environment
Helping the editor better understand the code you write, to give you auto-complete suggestions and tips for improving your document
Backend and client generation from API description will come back with support for version 2.0
Enabling users to set their own key bindings for the editor or change its color theme
Please check out the project's GitHub issues page to see them all.
Swagger Editor is open source and free. We're starting to get issues, pull requests, and contributions from the community, which is a great—and important! If you're interested in getting involved, get started by reading the docs, contribute a PR, and let us know if we can help!