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.
Here's what the Uber API looks like as a Swagger description.
There are Swagger plug-ins for most major IDEs that can quickly take a Swagger API definition and turn it into usable endpoints, ready for you to add code and build an appropriate app. That’s why major cloud service providers are adopting Swagger to deliver API descriptions as part of their services -- with Apigee using it in its API management platform and Microsoft using it in Azure’s new application platform.
Note that the autogenerated documentation produced by Swagger isn’t perfect. It can't capture the nuances of well-written man pages, and it often seems stilted and prescriptive. But if you use it as a framework for more detailed documentation, it’s a good way of kickstarting the process, and it should get documentation in the hands of developers quicker. Using the Swagger editor, you can take a framework API description and add more content, with a live documentation view showing what a user will see while you edit the API description.
Of course Swagger isn’t the first attempt at developing a language that can be used to describe APIs. Back in the days before REST defeated SOAP, the WS-* series of protocols were XML API descriptions that could be used in much the same way as Swagger is today, forming the foundation of the first API marketplaces and directories. There’s now a market for RESTful APIs, with services like Azure offering their own APIs, as well as a marketplace where third-party cloud services can be purchased and used in applications -- via tools like Swagger to deliver documentation to developers and to turn an API into a SDK.
It’s easy enough to start working with Swagger. If you’re using it to consume APIs, grab the appropriate Swagger endpoint for your IDE and start coding. If you’re using it to design and develop APIs, then a good place to start is the online editor on the Swagger website. It’s prepopulated with a sample API that you can use as a framework for building your own APIs.
Swagger specifications are stored at a specific URL on your site in two separate files. The first is a Resource Listing, showing the available APIs. The second, the API Description, is more detailed, listing the elements needed to call an API along with any descriptive text you’ve added.
Building your API description can be done in three different ways: You can add markup in your code that can be parsed by a Swagger tool to create a YAML description, you can use a tool to design your APIs and the Swagger description at the same time, or you can hand-code the Swagger description and use it to generate the code for your server APIs.
Hand-coding a Swagger API definition makes sense when you’re taking an API-first approach to application development, especially if you’re studying user stories to drive an agile development process. It’s worth thinking of your APIs as actors, with the calls as messages driving the appropriate outputs -- at which point you can start to map them, for example, to CRUD actions that can be used to define your API endpoints.
If you have an existing API, you can add declarative markup around it that can be parsed by a Swagger tool and used to generate the appropriate API documentation. It’s a relatively simple process to drop in descriptions at the appropriate place in your code. Once you’ve generated the Swagger files from your code markup, you can then use the Swagger editor to expand descriptions and make your API documentation user-friendly.
APIs are rapidly becoming the point of contact between all manner of applications and core systems of record. Without good documentation and effective API management, it’s going to be hard for developers to work with those systems, especially if they’re part of a continuous delivery system. As service-oriented or microservices approaches become more popular, technologies like Swagger will become essential.