Manage APIs with Swagger

The new API markup language Swagger enables devs to generate and document APIs easily

Become An Insider

Sign up now and get FREE access to hundreds of Insider articles, guides, reviews, interviews, blogs, and other premium content. Learn more.

The heart of a modern application isn't code anymore -- it’s the APIs that let us connect that application to the rest of the world.

In today's era of distributed, componentized, service-oriented development, an API is the public face of your application, the connection between a business and its partners, between a brand and its consumers. It’s a public face that needs to be well designed and documented because its value is realized only when it’s used.

If APIs are so important, then how can we design and document them effectively? One option comes in the shape of Swagger, an API markup language that can be used to generate both client and server code, as well as automatically produce documentation. Designed to work with RESTful APIs, it’s a useful tool for anyone building and managing modern applications -- especially where you’re delivering APIs to partners and departmental developers.

One of Swagger’s most useful features is a sandbox where you can experiment with an API before writing any code. Having code sample tools built into documentation is a powerful advantage: It lets you try out API interactions inside the supporting materials -- so you can see if your application will work before registering for an API key or before setting up an account on an API management gateway. Your developers will also be able to use Swagger-generated documentation to learn the ins and outs of an API before they add it to their code.

Swagger Uber API

Here's what the Uber API looks like as a Swagger description.

To continue reading this article register now