Swagger

A framework for describing, documenting, and consuming JSON webservices

Swagger is a specification and open-source framework for describing, producing, consuming, and visualizing RESTful web services with JSON. I created Swagger while building wordnik.com. Our team needed a tool to help make our APIs easier to document, understand, and use. In the four years since its creation, a large and active community has developed around Swagger, and people are continuing to find new and interesting ways to incorporate it into their JSON webservice implementations.

Origin Story

I gave a talk about the origin of Swagger at the API Specifications Conference 2020.

Here's the video:

Here's the transcript:

Hello, and welcome to the API Specifications Conference 2020. My name is Zeke Sikelianos, and this talk is called, "A Swagger Origin Story". First off, what is Swagger? This image embodies what Swagger means to me. It's a physical expression of happiness in the form of a walk. What was Swagger? The Swagger project. Swagger, now called OpenAPI, is a human-friendly and machine-readable language for designing, documenting, building, testing, and consuming HTTP web services. But where did Swagger come from? In 2007, I saw a TED Talk by lexicographer Erin McKean, who at the time worked for Oxford University Press. This talk discussed how language constantly evolves and how the dictionary is an antiquated mechanism for cataloging words. I found this to be a fascinating talk. Roger McNamee, a billionaire venture capitalist, was in the audience and liked Erin's talk. They spoke afterwards and formulated a business plan, raising money to create a startup called Wordnik.

Wordnik was, and is, a dictionary site at its essence. It aggregates English dictionary definitions from various sources like WordNet, Century Dictionary, Wiktionary, and American Heritage. We also gathered word information from other sources like Twitter, Wikipedia, Wiktionary. We collected images from Flickr and news articles from RSS feeds. I joined Wordnik in 2011. One of the most interesting concepts we worked on was "Free Range Definitions", a term coined by Erin McKean. This describes using a word in context to convey its meaning. The Wordnik website utilized many example sentences to help users understand words and glean their meaning from real-world usage.

We also worked on another interesting project at Wordnik: an app called "wordRainbow" to crowdsource color definitions, where users matched words to colors. We also developed an app for competitive rhyme generation, where teams would come up with rhyming words, and the highest score won. We collected all this data and used it in the Wordnik API. The Wordnik.com website was one consumer of the Wordnik API. We designed the service to be used by mobile apps, games, browser extensions, and publishers. We aimed to be the definitive source for English word data for developers.

We developed a site called developer.wordnik.com, listing all available API methods. We also published client libraries for interacting with the Wordnik API in various languages like iOS, Ruby Gem, Python, AS3, Knicker (Java), and PHP. The engineering team at Wordnik consisted of lexicographers, computational linguists, and web developers—a pretty great and fun group. We had cultural differences in preferred technologies and how we built things. Wordnik.com was a Ruby on Rails application with JavaScript on the front end and Node.js tooling. The api.wordnik.com was built with a completely different set of tools. Our linguists and backend developers used languages like Java, Scala, and Clojure, all JVM-compiled, to build the backend for api.wordnik.com. The API used a MongoDB database for persistence. At the time, Wordnik reportedly had the largest MongoDB installation globally, with about 10 gigabytes of data in 2011. The team working on it were thought leaders in scaling MongoDB.

I worked on the www team as a Rails developer. We couldn't directly access the database, so we used HTTP for all interactions on the Wordnik site through the Wordnik API. Let's talk about databases. Ruby on Rails is an awesome web framework for building "full stack" web applications and having fun while doing it. Rails uses the MVC (Model-View-Controller) software design pattern. The "M" in MVC stands for Model, which manages the data, logic, and rules of your application. Importantly, the Model abstracts away the database. If you don't like writing SQL queries, ActiveRecord is fantastic. ActiveRecord is Rails' object-relational mapper (ORM) that simplifies human interaction with databases. It offers a streamlined, chainable interface for querying, whether pulling data out or putting it in. ActiveRecord is designed around simple nouns, verbs, and relationships, making data interaction much easier to understand than SQL.

ActiveResource is another Rails project, similar to ActiveRecord. It's an ORM, but instead of abstracting databases directly, it abstracts remote HTTP web services. So, if you're building a Rails app without your own database and need to interact with a remote API, you can use ActiveResource to simulate ActiveRecord-like behavior. Unfortunately, because we used MongoDB, we couldn't fully leverage ActiveRecord's style for designing our Rails app models. ActiveResource also didn't map well to the existing Wordnik API; designing for it would have meant starting from scratch.

A snippet from a MongoDB blog post, "Each JSON document carries its own human-readable schema design with it wherever it goes, allowing the documents to easily move between database and client applications without losing their meaning," proved quite inspiring and influenced Swagger's development. My first challenge was: How can our Rails app interact with the Wordnik API in a way that's as fun and intuitive as using ActiveRecord? My second challenge was: How can we make using Wordnik's API a fun experience for all consumers, not just our internal developers?

At that time, in 2011, there was an XML specification called the Web Application Description Language (WADL). WADL was adequate, but our team wasn't interested in using an XML format to describe our data. Tony Tam, Wordnik's CTO and my boss, suggested I write a basic JSON file structure that described the API as we wanted to consume it from api.wordnik.com. We started with a very simple swagger.json file. It listed all API paths, and under each path, an operation consisting of an ID and a list of arguments or parameters. This marked the beginning of Swagger. We didn't call it Swagger then; we didn't even have a name for it when we first created it. The core idea was to have a contract between the website developers and the API developers, serving as our single source of truth for all teams. API developers would implement the API according to this specification, and website developers would implement their client for interacting with the API also according to this specification. We could also generate client libraries in multiple languages using this same specification. It was a very exciting and truly mind-opening moment in Wordnik's development history.

Here's an example of one of the first API responses we got with the Swagger spec: the word "tony" defined as "stylish, high-toned, upscale," which was very accurate for Tony Tam. We didn't want to "waddle" (walk with short, tilting steps, like a duck). We wanted to "swagger" (to walk with a lofty, proud gait). At the time, I only associated "swagger" with the dancing baby's happy dance. I started developing some Swagger logos. The first one was a bit too "smarmy," so we opted for something simpler. This simpler version worked better because we could use Google Fonts for consistent rendering across browsers.

Swagger UI was an interesting part of Swagger's development. Once we had a JSON specification, we realized we could easily consume it to render API documentation. I developed an API listing page with small, expandable, and collapsible rectangles for each operation. We arbitrarily chose colors to represent different HTTP verbs (red for DELETE, green for POST) to make the documentation more approachable and fun. We also realized that, since we knew everything about the API, we could generate dynamic forms with custom data types, essentially creating a sandbox to try out these API endpoints. We used this not just as a proof-of-concept for Swagger, but also internally for smoke tests to ensure we got expected results.

Here's an example of how you could get an API response body directly in the browser. We bundled all of this, publishing it at swagger.wordnik.com. We open-sourced several components: the Swagger UI tooling for generating UI documentation and sandboxes, and a Java-based Swagger code generator tool, written by Tony Tam's team, for generating clients in multiple languages. We also open-sourced the Swagger JS client, a JavaScript client that could consume a Swagger definition file and generate client code live. This was all very exciting.

Unfortunately, despite our cool open-source work with Swagger, Wordnik wasn't making enough money. Eventually, the Board of Directors got involved, hired new people, and the company pivoted to "Reverb," a recommendation engine for publishers. To me, this was a far cry from our original work at Wordnik, a signal that my time there was over, and it was time to move on.

So, for me, life after Wordnik immediately led to Heroku. I joined Heroku in mid-2012 as a Product Designer. I worked on the new Add-ons Marketplace, which, interestingly enough, was essentially an App Store for connecting databases to your Heroku applications. I also made the somewhat controversial decision to design Heroku's first light interface, making the blog white when all other Heroku properties had dark backgrounds. At this point, I was deeply involved in Node.js, starting to leave Ruby on Rails behind. I worked on building a new Node.js buildpack, allowing Node developers to publish their apps to Heroku much like Ruby developers could. My primary focus was on the Node developer experience.

Then, npm, Inc. became a company, and I couldn't resist the temptation to join. I moved to Oakland and started working with npm as a designer and developer. There, I created graphics like this one and designed and built the new docs.npmjs.com website and package pages. After npm, I moved on to GitHub, where I've been for four and a half years. I initially worked on Electron, which is still very much a Node.js project. Interestingly, Electron's documentation was initially unstructured Markdown. One of my biggest projects on the Electron team was to take this unstructured Markdown data and parse it into a structured, machine-readable format to generate TypeScript definitions for editors. This provided IntelliSense magic for developers writing Electron apps.

After a couple of years on the Electron team, I moved to GitHub Docs. I set my sights on help.github.com, which was an old, neglected app that lacked significant design or engineering attention. We rewrote this in Node.js. Then, we embarked on the effort to merge help.github.com and developer.github.com into a single, unified docs website: docs.github.com, which launched earlier in 2020. Previously, developer.github.com housed GitHub's REST API documentation. This was difficult for the internal team to maintain because we lacked a schema and weren't using Swagger or OpenAPI.

Here's a screenshot of what our source API documentation looked like for our REST API. It was a Frankenstein evolution of API documentation that was unstructured, piecemeal, and created by different teams over about 10 years at GitHub. We knew we wanted to move away from this. We wanted the API to be described closer to where it's actually developed, within the GitHub codebase, rather than living in Markdown files on the developer site. Gregor Martynus, a contractor at GitHub, did remarkable work to schematize and structure GitHub's previously unstructured API documentation. Gregor's "Octokit Routes" project essentially scraped the developer.github.com REST API documentation and transformed it into a structured schema that very closely resembles an OpenAPI schema.

When I was working on Docs, I collaborated closely with Gregor and other contractors to take this Octokit Routes data, which was scraped nightly by robots, and transform it into something more official. We've managed to complete that process. As of just a couple of months ago, the REST reference documentation now lives on docs.github.com and is powered by an OpenAPI specification. It has much of the same information as before, but with added features. Most notably, we can now generate code samples for different client languages, like Shell and Octokit examples, allowing developers to easily copy and use these APIs directly. This is just the beginning; we plan to expand on what we display on the website using the OpenAPI definition.

We recently open-sourced our OpenAPI description files for GitHub's REST API. You can find them at github.com/github/rest-api-description. We're still in the process of moving the REST API description into the main GitHub codebase so that it can be more deeply integrated into the design process. This means that when developers are building new APIs within GitHub, they can adopt a design-driven approach using OpenAPI description files. Finally, GitHub now has a public roadmap! If you're a GitHub customer and want to know what's on the horizon or what new features will launch next year, check out github.com/github/roadmap. I bring this up because we're open-sourcing docs.github.com in about a month or so. All the tooling that currently lives behind closed doors, used to work with OpenAPI descriptions, will soon be open-sourced. Stay tuned for that.

I hope you enjoyed this talk. Thanks for your time. Take care, be safe, and party on!