11436 SSO

A Design-First Approach to Building APIs with Swagger

May 22, 2014

APIs are often designed and documented after they've been developed. What if you could design your API collaboratively, using simple markup?

We think the best APIs are built in conversation between the app developers who’ll use the APIs and the API developers who want to figure out how to unlock the power of their back-end services. We believe that APIs can be built using a simple, human-readable format and can be collaborated on using tools like GitHub before any code is written. And we think sophisticated tools can be built and services automated, such as mock APIs. All this is possible with a simple modeling language.

In the last three years, Swagger has been wildly successful; it’s estimated to be used in 10,000 production deployments. GitHub developers have forked Swagger projects over 1,600 times and have added over 4,100 stars. The framework for Java has been downloaded over 500,000 times! This success in the marketplace is why Apigee's SmartDocs feature supported Swagger descriptions at launch. Swagger is also the format of choice for projects including the API Commons and for big enterprises like IBM and Intuit.

As the first JSON-based API description format in the public domain, it came about at a time when JSON was beginning to displace XML. Swagger is language agnostic; this has been critical to its adoption, as it enables developers to implement the Swagger specification in the language and framework of their choice.

WSDL and WADL failed to cross languages and therefore developer communities, but Swagger has thrived, with community contributions easily outnumbering those from the team at Reverb. While the Swagger framework makes it easy to generate API descriptions from source code, it hasn't yet been easy to use Swagger as an API modeling tool, because writing and editing JSON by hand is still hard work. But that's about to change.

Apigee is proud to contribute an open source project that helps people write Swagger specifications using YAML. This editor enables people to work with APIs in a more human-friendly syntax when creating API specifications in Swagger. Those specifications can then be used with Swagger tooling as well as SmartDocs. We've been working closely with Tony Tam, the driving force behind Swagger, to refine the grammar and to enable an API design-first approach in the Swagger ecosystem.

At Apigee, we believe that code talks loudest, so our first contribution to this effort is a Swagger editor that lets you view your API docs side-by-side, in sync with your YAML editing.



This is a great way to get started with Swagger and a powerful productivity tool for API designers. Like everything around Swagger, it is proudly open source and we’ve made the code available on GitHub under an Apache license. Apigee Edge users can look forward to integrations in the Apigee Edge user interface.

This is just the starting point. We’re also proud to be a founding member of a new working group formed to advance the Swagger specification. Swagger 2.0 is an opportunity to improve on version one in a number of areas, including element renaming, structural changes, and allowing for vendor extensions while keeping the format simple, open, and accessible by anyone.

There’s an opportunity to better define how things like API hypermedia are designed and documented within Swagger, and, equally important, there are a lot of great tooling opportunities that you’ll see within Apigee’s products. Ultimately, we want to make it possible to define many runtime behaviors such as security configuration within Swagger.


Finally, a little trivia: While the Swagger codebase was born in the Wordnik offices, it was named in an Apigee office. During discussions with Wordnik about the possibility of open sourcing their technology stack, Zeke quipped, "Why WADL when you can Swagger?"

We have deep respect for the work Reverb (formerly Wordnik) has invested in the Swagger specification, framework, and tooling, as well as for the thoughtful stewardship of its vibrant community. We have high hopes for the future of Swagger, and we look forward to being a part of its next iteration.


Scaling Microservices