ElegantSpiceworks

Web applications often offer a REST interface for external use of their services. Developers address this from their own programs by accessing it through special URLs and HTTP requests, assuming the REST API is documented as completely as possible. A library that allows for a more convenient access to the service and thus facilitates the process of writing client programs would be even better.

However, for the web application vendor this involves much work: They not only need to develop the documentation and the library but also update both in case of any interface changes. A miracle tool named Swagger [1] automates both. Swagger is both a specification [2] and a collection of tools that generate interactive documentation for a REST API, and it's even a small software development kit (SDK) for client programs on request.

Division of Responsibilities

What initially sounds complicated proves to be remarkably simple in practice [3]. First, the developer describes the feature set of their REST API in a text file; it is written either manually or generated automatically from the source code of the web application. Generating it automatically implies that one of the frameworks supported by the Swagger tools is used, including JAX-RS [4] and Node.js [5]. In any case, two tools then access the API description and produce a complete API reference, as well as a matching SDK. The developer integrates the Swagger tools in the build process; the documentation and client SDK are automatically kept up to date.

Swagger, developed by SmartBear [6], comprises in part a comprehensive specification [2]. It describes in detail how the developer has to write the REST API in the text file. SmartBear handed over the complete specification of Swagger January 1, 2016, to the Open API initiative [7], which in turn is backed by the Linux Foundation. The specification was renamed OpenAPI Specification [8]. Because it is based on version 2.0 of the Swagger specification, the OpenAPI Specification also has this version number.

Hammer and Chisel

Centered on the specification, SmartBear has published a number of useful tools, including the Swagger Editor [9], with which the user conveniently can create and edit the description of the REST API. It not only includes syntax highlighting but checks the description for syntax errors against the Swagger specification. Errors are generally highlighted in color; it also gives you formatting tips and displays a preview of future documentation.

One of the most important tools in the bunch is the Swagger user interface (UI). It creates practical interactive HTML documentation from the description of the REST API. Users can call the functions of the service directly from the documentation if needed.

The Swagger makers demonstrate what this kind of documentation looks like on their website, providing a fictitious online pet shop that users can control via a REST interface. Thanks to the API reference [10] created with Swagger, users can both see the functionalities offered by the online shop and add new animals with a few mouse clicks (Figure 1). The Swagger UI is written completely in HTML, CSS, and JavaScript; developers quite simply adapt the look of the documentation to suit their needs (Figure 2) [11].

Figure 1: On the Swagger UI, the developers offer a (fictional) online shop with a REST interface. The documentation generated by Swagger describes its structure.

Figure 2: Documentation of the Watson Developer Cloud's REST API was also created with the help of Swagger and provides a first impression of the results.

The Swagger codegen [12] tool generates a complete SDK from the description of the REST API, which developers can eventually use to author client applications for the service. The SDKs are created for various programming languages – ranging from Java, Python, PHP, and Ruby to Scala. Swagger makers like to call the complete package, comprising of the Swagger specification and the associated tools, the API framework.

All the tools mentioned are under the liberal Apache 2.0 license. The complete Swagger framework is used, according to SmartBear, by Getty Images, Microsoft, and PayPal (see also the "Swagger in the Wild" box).

Building Plan

The REST API can be easily described in the Swagger Editor, a web application that requires a web server. If you want to save the trouble of installing, you can use the editor directly on the Swagger homepage (Figure 3) [9]. Operators of a (local) web server first download the swagger editor.zip archive for the current Swagger editor (not the source code) [15]. Unzip this and then upload the complete contents of the swagger-editor directory to the web server or the local DocumentRoot directory.

Figure 3: In the Swagger Editor, web application developers can conveniently describe the REST API. The example relates to the (fictional) Swagger Petstore, to which you can add animals yourself.

If you don't want to install a web server, you can resort to the Node.js module http-server. Install this and launch the commands in Listing 1 on Ubuntu. You also install the latest 2.10.1 version of the Swagger Editor on your disk at the same time. After entering all the commands, you can access the editor on http://localhost:8080 . Docker fans can power up the editor with two Docker commands:

docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor

¤¤nonumber
01 sudo apt-get install npm nodejs-legacy
02 sudo npm install -g http-server
03 wget https://github.com/swagger-api/swagger-editor/releases/download/v<2.10.1>/swagger-editor.zip
04 unzip swagger-editor.zip
05 http-server swagger-editor

In any case, you are taken to the user interface shown in Figure 3. Type in the description of the REST API on the left; on the right you will either see a preview of the documentation or an error message, parallel to this.

By default the editor shows a slightly more complex example below File | Open Example, but a few easier ones can also be found. The minimal.yaml example is well suited as a skeleton for your own descriptions. It is slightly more compact than the skeleton created by File | New.

Next, you describe the structure of the REST API in either JSON or YAML format. The latter is a little easier to read but uses indentation to structure the code. Listing 2 shows a simple example of an API description in YAML, which is based in turn on the example echo.yaml. It describes the REST interface of the echo service [16] and simply returns all the information sent to it back to the sender.

¤¤nonumber
01 swagger: '2.0'
02 info:
03   title: Echo example
04   version: 1.0.0
05   description: |
06     #### Returns each URL, method, parameter and header
07     The echo server simply returns **every** value.
08 schemes:
09   - http
10 host: mazimi-prod.apigee.net
11 basePath: /echo
12 paths:
13   /test:
14     get:
15       responses:
16         200:
17           description: Echo via GET method
18     post:
19       responses:
20         200:
21           description: Echo using POST method
22       parameters:
23         - name: name
24           in: formData
25           description: A sample parameter
26           type: string