« Previous 1 2 3 Next »
Swagger and OpenAPI Specification for documents
ElegantSpiceworks
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.
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.
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.
« Previous 1 2 3 Next »
Buy this article as PDF
(incl. VAT)