Swagger: a practical solution for developing APIs

In development projects, creating documentation is very time-consuming, and outsiders often do not realise how important it is for maintaining and further developing systems. At best, this becomes apparent when a team other than the development team try to carry out maintenance and make improvements – and this scenario is the rule rather than the exception.

Documenting APIs, or Application Programming Interfaces, is even more important. APIs connect applications with one another and with data sources and other systems. Nowadays APIs play a key role in connecting software in almost every kind of system. However, to be able to use these interfaces, you have to know about their structure and functions. This is where the OpenAPI specification Swagger comes in. It is an open description format that helps provide an overview of the various capabilities of APIs. Using Swagger, even teams who were not directly involved in the development process can set up APIs. They can see the interfaces used and instantly create the documentation.

In the past, describing APIs was a complex task due to the number of different technologies and programming languages. Since then, REST has become the programming model for the development of APIs, which was a big step towards a more orderly system. Websites like Google, Amazon and Twitter use RESTful APIs. Previously, interfaces were described using Web Services Description Language WSDL. From a purely technical point of view, it is possible to describe REST APIs using WSDL 2.0. However, developers tend to find this rather cumbersome. Web Application Description Language (WADL) was introduced to solve this problem, but due to its XML structure it has never been standardised.

This explains why Swagger quickly earned its place as the most popular technology for API documentation – or, more accurately, as the most popular technology for the frequently used REST APIs. Swagger was developed by Reverb but is now vendor-neutral and available under an open-source licence via the OpenAPI Initiative, a Linux Foundation project. As part of this, Swagger was renamed the OpenAPI Specification, but unofficially it still goes by its catchier name, Swagger.

Depending on the field of application, the core element of Swagger is either a JSON or a YAML file. The user interface (UI), which provides an easy way of creating the API documentation, is based on HTML and JavaScript. Put simply, Swagger is language-neutral and machine-readable. Via the user interface, developers can not only manage documentation, but also use Swagger to run ad-hoc tests.

One advantage of Swagger is its comprehensive extension mode, which is supported by a core library known as the Swagger Core. The user interface is called Swagger UI and the code generator is called Swagger Codegen. There is also a Swagger Editor.

However, Swagger’s greatest strength – as with many open-source solutions – comes from its extensive ecosystem on GitHub. There are code generators for almost every programming language. Swagger documents each interface with all the necessary information.

The documentation file starts with the specification version number, and then gives the general information about the API, clearly organised under the ‘info’ category. Swagger also separates out the host, the path, and URL schemes and specifies each of these. After this it gives the MediaType for the entire API. You can think of the structure like a complex index card system.

Once everything has been categorised, the content is presented: paths, operators, and parameters and their descriptions are prepared. Data types are dealt with in a separate section. In the Swagger UI, everything can be displayed both in text form and graphically. This is especially useful when sending direct test requests from a browser. This combination of perfect documentation and the ability to generate direct API requests is what makes Swagger so valuable.

When developing an API, it’s essential to have well-organised, understandable documentation. Without this, developers cannot use the interfaces. This is especially true for public APIs – they would be useless to the community if they had no documentation.

Swagger is currently the best way of documenting REST APIs because it can map almost all web services and required information. It evolves with the system and all changes are automatically documented. The reason this works so well is because Swagger puts the REST API documentation directly into the code.

The starting point of every API development is either the program code (‘Code First’) or the interface description (‘Design First’). In the Code First approach, the program code is the agreed starting point. From this, Swagger can directly derive documentation that is independent of the programming language used and can be read both by humans and machines.

The alternative approach is Design First. As mentioned above, client-side and server-side development is often carried out by different teams. In a Design First approach, the first step is to prepare the description. The code is then generated using Swagger. There are generators for all common programming languages, and the templates can be customised and expanded.

With Swagger, the process of generating consistent API code is therefore almost entirely automated. If something in the manual programming isn’t correct, there will be compilation errors, which can be detected in a Continuous Integration System.

The advantages of Swagger far outweigh its disadvantages – so much so that Swagger can be considered an excellent standard application for describing interfaces for RESTful APIs. Like lots of open-source applications, Swagger is widely distributed and there is consequently extensive tool support. Its committee includes tech giants such as Microsoft, IBM, and Google, which means the OpenAPI specification has significant backing. Alternatives do exist, such as Restful API Modeling Language (RAML), which is also based on YAML and can create even more complex definitions than Swagger. However, the creator of RAML (MuleSoft) has now joined the OpenAPI Initiative.

A slight drawback of Swagger is the readability of its documentation. It’s true that it offers a fairly well-prepared format, but it takes a while to get used to. API Blueprint, which uses a markdown syntax, proves that it can be done more simply.

You can download the complete Swagger ZIP package from the Swagger UI website. After downloading the package, you will be asked whether you want to run Swagger locally or on a server.

Note: If you want to run it locally, you’ll need MAMP. Once unzipped, the Swagger UI Master will be placed either in the MAMP directory or on the server. You can then simply call the URL of the server or the local host in a browser, and Swagger will automatically open and start the first API documentation.

The web version of the Swagger Editor provides an even simpler option. You can use it directly in a browser, with the added benefit of having a graphical version of the documentation displayed alongside the text editor.

This short Swagger example clearly shows the understandable structure. All information is clearly labelled and can be understood independently of a programming language.

The documentation can be exported directly as a YAML file or first converted to JSON format. This is the documentation file that can be read in the Swagger UI. The displayed contents start with the paths, interfaces, and endpoints. After this come the descriptions and parameters, and the responses and their meanings. Ad-hoc tests can be performed at the endpoints via the Swagger UI.

And of course, the good thing about open-source tools is that you can try them for free. This is true both for the Swagger user interface and all other tools, so give it a try and see for yourself what Swagger can do!