What is Swagger and Why Does it Matter?

In the early 1800s, the American railroad was a free-for-all. Every city had its own time calculation, which meant that there were over 300 different time zones across the country. This made train schedules incredibly difficult to coordinate and long trips nearly impossible to plan.

At a time when trains were a popular method of transportation, this posed an imminent problem. The only solution was to instate time zones, creating an industry standard for all American railroads. As a result, railroads connected the whole world and helped to spark the industrial revolution. What’s the takeaway?

For millions of people to communicate, there needs to be a common vocabulary.

In the software industry, the API landscape is facing a similar issue. Great code is crucial for modern businesses, and the best way for us to connect and share data is through APIs. But not only has there been no industry standard for designing APIs, there hasn’t been an industry standard for documenting them, either.

APIs are supposed to connect engineers and allow for the sharing of great developments. APIs let companies like Twilio add value to other products and create an ecosystem of shared knowledge. But an API is only valuable if it’s accessible. And for that, it needs clear documentation.

Terrible documentation is just as useless as a clock that tells the wrong time. Developers have worked hard to find a way to standardize the vocabulary surrounding APIs. That’s where Swagger comes in. Swagger is basically a set of rules (specification) and tooling for how to semantically describe APIs. Practically, it’s a language-agnostic tool that gets everyone on the same page.

Swagger in a nutshell

Swagger (now the “Open API Initiative” — more on that later!) is a framework for describing your API using a common language that everyone can understand. Think of it as a blueprint for a house. You can use whatever building materials you like, but you can’t step outside the parameters of the blueprint.

There are other available frameworks that have gained some popularity, such as RAML, APIBlueprint, and Summation. But Swagger provides more benefits than just helping create clear documentation:

• It’s comprehensible for developers and non-developers. Product managers, partners, and even potential clients can have input into the design of your API, because they can see it clearly mapped out in this friendly UI.
• It’s human readable and machine readable. This means that not only can this be shared with your team internally, but the same documentation can be used to automate API-dependent processes.
• It’s easily adjustable. This makes it great for testing and debugging API problems.

These three benefits not only make developers’ lives easier, but they make the API more consumable. Any API that adheres to the Swagger spec is easy to read, easy to iterate, and easy to consume. That’s why huge companies like Netflix, Akana, and Yelp jumped on the Swagger train.

The rise of design-first APIs

With this blueprint in mind, there are two main ways to take advantage of Swagger:

• Top-down approach, or design-first. This means you’re using Swagger to design your API before you’ve written any actual code.
• Bottom-up approach, or code-first. This means you’ve already written the code for your API, and you’ll be using Swagger to document your API.

In the early days, it was popular for APIs to be created code-first. This is much easier because you can make adjustments as you go, and it fits nicely into an Agile delivery process. But because you’re not thinking about the design, this can make for an API that’s difficult to understand and document.

The push for clear, easy-to-read documentation has popularized the design-first approach. Not only can more people have input on your documentation, but it actually results in cleaner code. You’re forced to think simpler and more concise.

The Swagger toolbelt

At the heart of Swagger is its specification. The Swagger spec is the rulebook that standardizes API practices (how to define parameters, paths, responses, models, etc). Every other part of Swagger is just a way of appropriating or creating API documentation that works with these rules.

While the spec is the lifeblood of the framework, Swagger has been an open source project since its inception. That means that an entire ecosystem has formed around this initiative that not only optimized the rulebook, but built handy tools for its use (SDK generation, dynamic documentation, and server integrations).

Here are a few of the basic tools that help implement Swagger:

The editor

The Swagger editor is a convenient tool that addresses this issue. You can write up your documentation in YAML or JSON and have it automatically compared against the Swagger spec. Any mistakes are flagged, and alternatives are suggested. This way, when you publish your documentation you can be sure that it’s error-free.

The user interface

One of the reasons that documentation sucks up so much of a developer’s time is because it needs to be very organized and navigable. You have to worry about where to put examples, how to organize your methods, and how much detail to provide for each call.

One option for displaying your Swagger file is the Swagger-UI. This takes an existing JSON or YAML document and creates interactive documentation. You’ll come up with something that looks like this.

Each method (get, put, post, delete) is expandable. By clicking “expand operations,” you get a full description of the parameters with an automatically generated example. You can test call values and see the response message. This is convenient, but unfortunately not yet a great user experience (which is where interactive documentation and developer hubs come in).

Changing the API landscape

Similar to how Git has become the de facto open-source platform for developers, Swagger has emerged as the most popular approach to API design. In 2015, it was moved to the Linux Foundation under the name The Open API Initiative, and is now backed by companies such as Google, Microsoft, Intuit, and Atlassian. The initiative “is focused on creating, evolving and promoting a vendor neutral description format.” Having a common language for describing APIs will make tooling much easier to use, and will change how we make and consume APIs.