Swagger and OpenAPI Specification for documents
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].
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).
Swagger in the Wild
Atlassian [13], a manufacturer of tools like JIRA, Confluence, and BitBucket, also increasingly deploys Swagger. In interviews with Linux Magazine at AtlasCamp 2016, several employees said they were quite fond of the tool. Swagger had not been imposed from above, but several groups had initially used it independently of each other. They especially underlined automatic generation of documentation as Swagger's strength, even if the specification could still use some optimization in some places.
The company has now officially joined the Open API Initiative, is contributing to development of the OpenAPI specification, and has published the RADAR [14] API documentation generator under the Apache 2 license.
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.
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
Listing 1
Swagger Editor with Node.js
¤¤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.
Listing 2
Swagger Spec for the Echo Service
¤¤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
Buy this article as PDF
(incl. VAT)