Nested Characters

In line 1 of Listing 2, swagger is followed by the version number of the underlying Swagger specification. The subsequent info block provides some basic information. The service is named in the title line, and it is later seen in bold as a heading in the documentation (e.g., Swagger Petstore (Simple) in Figure 3).

The API offered by the Echo service  [16] exists as version 1.0.0, which is revealed by the entry in line 4. In other words, neither the version of the service nor the Swagger specification version number follows. The line starting with description briefly describes the service. The text following the hashes (#) and the text between asterisks (*) is printed in bold type later.

The transfer protocols used by the service follow schemes; the Echo service accepts only HTTP requests. Line 10, which begins with host, is followed by the hostname or IP address of the service, both without further parameters or prefixes. Only a port specification is allowed. The base path to the service follows separately behind basePath. Developers enter this relative to the hostname prepended with a slash. In the example, the echo service thus is available on the Echo server [16].

The resources that exist there and the operations that clients can perform on them are defined in the block below paths. The example has only one resource, /test. The GET and POST methods can be run on it. GET always delivers a status code of 200 (success); description is followed by a short, but informative, description of the operation.

The POST method additionally has a parameters section, which is a string, as defined by type in the last line, named name. Details about how the service transfers the parameters follow in (line 24); additional supported values are query, header, path, formData, and body.

The documentation generated by the editor from this description is shown in Figure 4. Using Try this operation developers can also try out the method directly. It only works in the editor if the service is allowed to perform a cross-origin call. This is usually not permitted for security reasons, meaning that the request will fail.

Figure 4: The editor creates the documentation on the right for the description in Listing 2.

UI in Action

The developer now downloads the final specification – either in YAML format via  File | Download YAML or as a JSON file with  File | Download JSON. You then install the Swagger UI and point it at the JSON or YAML file.

To do so, first download the current source code archive for the Swagger UI [17]. On unzipping, several directories are created. Using the browser, open the index.html file in the dist subfolder. If you want to publish the documentation, you only need to push the contents of the dist subfolder to the web server or the corresponding DocumentRoot.

In any case, the Swagger UI that appears in the browser first presents the sample documentation for the fictitious online pet store (as shown in Figure 1). For the UI to display the documentation for your own REST API, you need to copy the file created with the Swagger Editor dist directory.

Open the index.html file in a text editor and replace http://petstore.swagger.io/v2/swagger.jsonurl at the top after url= with the file name of the JSON or YAML file. If you will be using the Swagger UI offline and opening index.html directly in the browser, you need to specify the full path to the file, as in /home/tim/swagger-ui/dist/swagger.yaml. The Swagger UI then grabs this file and generates the appropriate documentation. For the description from Listing 2, the API reference then looks like Figure 5.

Figure 5: The Swagger UI showing the documentation for the REST interface in Listing 2.

The Swagger UI not only delivers the documentation but also always tries to validate the description against the Swagger specification. This only works if the description is publicly accessible. If it is only used offline or on an intranet, a red Error message appears in the bottom right corner. If you want to get rid of this, you need to modify the source code in the Swagger UI.

User-Friendly Clientele

The Swagger Editor can directly generate a client SDK from the description. To do this, open the Generate Client menu and select the desired programming language. This gives you a ZIP archive containing all the files necessary for client development, including the README.md, which briefly describes how to set up and operate the SDK. The documentation generated in Figure 5 is not part of the SDK.

As an alternative to the editor, you can create the SDK with Swagger codegen [18]. This command-line tool requires at least Java 7. If a corresponding JRE is installed, you can pick up the final version 2.1.6 of codegen with the command:

wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.1.6/swagger-codegen-cli-2.1.6.jar -O  swagger-codegen-cli.jar

Afterward, type

java -jar swagger-codegen-cli.jar help

for a list of all available command-line options. If you want to find out what programming languages are supported by codegen, you can do so with the command:

java -jar swagger-codegen-cli.jar langs

In the list of shortcuts, look for the desired programming language and then call Swagger codegen accordingly. The following example would produce an SDK for Python, where the description of the REST API resides in the swagger.yaml file, and the finished SDK ends up in the directory mysdk:

java -jar swagger-codegen-cli.jar generate -l python -i swagger.yaml -o mysdk

Finally, for Java developers, a Swagger Core package is available online [19] with several libraries that read and create Swagger descriptions. The Swagger Editor also generates a basic framework for an appropriate server application from the API description. To do this, you need to open the Generate Server menu and select the preferred framework. Swagger thus also helps to build a REST API.