Please welcome a new column: “Disrupt of the Week.” In this column I talk about the most breakthrough technologies that substantially change the rules of the game in various fields.
This week’s disrupt is Swagger (pronounced “swogger”) — a specification for describing web service APIs.
Why is this needed? Since the specification is machine-readable, you can use it as the basis for various useful things:
a) automatically generate documentation for a web service;
b) automatically generate API clients for this service;
c) automatically generate web service templates;
This is very relevant for microservice architectures, where one microservice can be used by other microservices written in different languages.
The specification is described in YAML or JSON. I prefer the first option because it is the most human-readable. This is what a specification looks like:
This is what a fragment of documentation built from this specification looks like:
And now for the most interesting part: there is an API client generator for many languages:
android, async-scala, csharp, dart, flash, python-flask, java, javascript, jaxrs, inflector, jmeter, nodejs, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra, slim, spring-mvc, dynamic-html, html, swagger, swagger-yaml, swift, tizen, typescript-angular, typescript-node, akka-scala, CsharpDotNet2, clojure
Here is a small fragment of an API client for the Objective-C language:
The implementation details of data exchange over the HTTP protocol are hidden from the developer. There’s no need to focus on those details. There are already ready-made high-level methods for working with the web service. You can describe the API once and generate two clients at once, for example, for a mobile application and for a website.
This way of describing a server API and generating clients increases a developer’s productivity by at least 10 times.