In de­vel­op­ment projects, creating doc­u­ment­a­tion is very time-consuming, and outsiders often do not realise how important it is for main­tain­ing and further de­vel­op­ing systems. At best, this becomes apparent when a team other than the de­vel­op­ment team try to carry out main­ten­ance and make im­prove­ments – and this scenario is the rule rather than the exception.

Doc­u­ment­ing APIs, or Ap­plic­a­tion Pro­gram­ming In­ter­faces, is even more important. APIs connect ap­plic­a­tions with one another and with data sources and other systems. Nowadays APIs play a key role in con­nect­ing software in almost every kind of system. However, to be able to use these in­ter­faces, you have to know about their structure and functions. This is where the OpenAPI spe­cific­a­tion Swagger comes in. It is an open de­scrip­tion format that helps provide an overview of the various cap­ab­il­it­ies of APIs. Using Swagger, even teams who were not directly involved in the de­vel­op­ment process can set up APIs. They can see the in­ter­faces used and instantly create the doc­u­ment­a­tion.

IONOS Developer API
Manage your hosting products through our powerful API
  • DNS man­age­ment
  • Easy SSL admin
  • API doc­u­ment­a­tion

What is Swagger?

In the past, de­scrib­ing APIs was a complex task due to the number of different tech­no­lo­gies and pro­gram­ming languages. Since then, REST has become the pro­gram­ming model for the de­vel­op­ment of APIs, which was a big step towards a more orderly system. Websites like Google, Amazon and Twitter use RESTful APIs. Pre­vi­ously, in­ter­faces were described using Web Services De­scrip­tion Language WSDL. From a purely technical point of view, it is possible to describe REST APIs using WSDL 2.0. However, de­velopers tend to find this rather cum­ber­some. Web Ap­plic­a­tion De­scrip­tion Language (WADL) was in­tro­duced to solve this problem, but due to its XML structure it has never been stand­ard­ised.

This explains why Swagger quickly earned its place as the most popular tech­no­logy for API doc­u­ment­a­tion – or, more ac­cur­ately, as the most popular tech­no­logy for the fre­quently used REST APIs. Swagger was developed by Reverb but is now vendor-neutral and available under an open-source licence via the OpenAPI Ini­ti­at­ive, a Linux Found­a­tion project. As part of this, Swagger was renamed the OpenAPI Spe­cific­a­tion, but un­of­fi­cially it still goes by its catchier name, Swagger.

Be32j9sNyfE.jpg To display this video, third-party cookies are required. You can access and change your cookie settings here.

Depending on the field of ap­plic­a­tion, 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 doc­u­ment­a­tion, is based on HTML and JavaS­cript. Put simply, Swagger is language-neutral and machine-readable. Via the user interface, de­velopers can not only manage doc­u­ment­a­tion, but also use Swagger to run ad-hoc tests.

One advantage of Swagger is its com­pre­hens­ive 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 gen­er­at­ors for almost every pro­gram­ming language. Swagger documents each interface with all the necessary in­form­a­tion.

The doc­u­ment­a­tion file starts with the spe­cific­a­tion version number, and then gives the general in­form­a­tion 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 cat­egor­ised, the content is presented: paths, operators, and para­met­ers and their de­scrip­tions are prepared. Data types are dealt with in a separate section. In the Swagger UI, everything can be displayed both in text form and graph­ic­ally. This is es­pe­cially useful when sending direct test requests from a browser. This com­bin­a­tion of perfect doc­u­ment­a­tion and the ability to generate direct API requests is what makes Swagger so valuable.

What is Swagger used for?

When de­vel­op­ing an API, it’s essential to have well-organised, un­der­stand­able doc­u­ment­a­tion. Without this, de­velopers cannot use the in­ter­faces. This is es­pe­cially true for public APIs – they would be useless to the community if they had no doc­u­ment­a­tion.

Swagger is currently the best way of doc­u­ment­ing REST APIs because it can map almost all web services and required in­form­a­tion. It evolves with the system and all changes are auto­mat­ic­ally doc­u­mented. The reason this works so well is because Swagger puts the REST API doc­u­ment­a­tion directly into the code.

The starting point of every API de­vel­op­ment is either the program code (‘Code First’) or the interface de­scrip­tion (‘Design First’). In the Code First approach, the program code is the agreed starting point. From this, Swagger can directly derive doc­u­ment­a­tion that is in­de­pend­ent of the pro­gram­ming language used and can be read both by humans and machines.

The al­tern­at­ive approach is Design First. As mentioned above, client-side and server-side de­vel­op­ment is often carried out by different teams. In a Design First approach, the first step is to prepare the de­scrip­tion. The code is then generated using Swagger. There are gen­er­at­ors for all common pro­gram­ming languages, and the templates can be cus­tom­ised and expanded.

With Swagger, the process of gen­er­at­ing con­sist­ent API code is therefore almost entirely automated. If something in the manual pro­gram­ming isn’t correct, there will be com­pil­a­tion errors, which can be detected in a Con­tinu­ous In­teg­ra­tion System.

Fact

Big companies such as Zalando follow the principle of API first and rely on Swagger for this. The de­velopers of the sale platform realise how important it is to have func­tion­ing in­ter­faces, so they choose to focus on this. In­tern­ally, APIs are used between the services of different teams, and ex­tern­ally there are APIs for re­triev­ing items or eval­u­ations for example.

Swagger – order can only be a good thing!

The ad­vant­ages of Swagger far outweigh its dis­ad­vant­ages – so much so that Swagger can be con­sidered an excellent standard ap­plic­a­tion for de­scrib­ing in­ter­faces for RESTful APIs. Like lots of open-source ap­plic­a­tions, Swagger is widely dis­trib­uted and there is con­sequently extensive tool support. Its committee includes tech giants such as Microsoft, IBM, and Google, which means the OpenAPI spe­cific­a­tion has sig­ni­fic­ant backing. Al­tern­at­ives do exist, such as Restful API Modeling Language (RAML), which is also based on YAML and can create even more complex defin­i­tions than Swagger. However, the creator of RAML (MuleSoft) has now joined the OpenAPI Ini­ti­at­ive.

A slight drawback of Swagger is the read­ab­il­ity of its doc­u­ment­a­tion. 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.

A practical Swagger example

You can download the complete Swagger ZIP package from the Swagger UI website. After down­load­ing 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 auto­mat­ic­ally open and start the first API doc­u­ment­a­tion.

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 doc­u­ment­a­tion displayed alongside the text editor.

swagger: "2.0"
info:
    description: "This is an example of Swagger"
    version: "1.0.0"
    title: "Swagger Example"
    termsOfService: "http://swagger.io/terms/"
basePath: "/v2"
tags:
- name: "Example"
    description: "Examples of Swagger"
    externalDocs:
        description: "More information"
        url: "http://example.org"
schemes:
- "https"
- "http"
paths:
    /Example:
    /Example/Contents:
        get:
            tags:
            - "Example"
            summary: "Get example elements"
            produces:
            - "application/json"
            parameters: []
            responses:
                "200":
                    description: "successful operation"
                    schema:
                        type: "object"
                        additionalProperties:
                            type: "integer"
                            format: "int32"
            security:
            - api_key: []

This short Swagger example clearly shows the un­der­stand­able structure. All in­form­a­tion is clearly labelled and can be un­der­stood in­de­pend­ently of a pro­gram­ming language.

The doc­u­ment­a­tion can be exported directly as a YAML file or first converted to JSON format. This is the doc­u­ment­a­tion file that can be read in the Swagger UI. The displayed contents start with the paths, in­ter­faces, and endpoints. After this come the de­scrip­tions and para­met­ers, 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!

Go to Main Menu