This week we are revisiting some classic articles from our archives. This article was first published on July 22 2015. Enjoy!
This article details the steps required to install and configure the Swagger UI tool on a WebSphere (8.0, 8.5.5 and 9.0) application server, which allows app developers to view and test out a Cúram REST API. This article is intended for developers of Cúram REST APIs who want to install the Swagger UI tool in order to fully document their APIs and allow other developers to discover and test those APIs.
- A Cúram application (version 6.1 or later), which includes a REST application, must be already running on a WebSphere server. This article assumes that the Cúram application is running on port number 9044. If a different port number is being used, please update accordingly when the port number is referenced.
- This article assumes that v1 of the API is being used. The Swagger specification will be available at https://<
It is not necessary to view the Swagger specification directly, as it is not in a very human readable format, however if required, it can be viewed using a REST client or cURL command. The URL cannot be accessed directly in a browser because the Referer request header must be set, for security purposes.
Downloading and Configuring Swagger UI
- Download the Swagger UI tool from the swagger-api GitHub repository at https://github.com/swagger-api/swagger-ui.
Note: Ensure that the Swagger UI version downloaded is compatible with Swagger Spec 2.0, as this is the Swagger spec version that is generated by the Rest application.
- Extract the downloaded swagger.zip file. Copy the ‘dist’ folder that is inside the swagger.zip file to a new location. This is the only folder that is required. It contains pre-built files that are ready to use out of the box.
- Rename the ‘dist’ folder to ‘swagger’.
- In the ‘swagger’ folder, open the index.html file with a text editor. Modify the following line, which specifies the default value for the ‘url’ property, from:
url = https://<
Note: If this step is not performed, when the Swagger UI tool starts up, it will display the API resources for the Swagger pet store sample application.
- Open a command prompt and change directory to be inside the ‘swagger’ folder. Run the following command, using Java 6 or higher:
jar –cvf swagger.war *
This packages the Swagger UI tool into a swagger.war file, in the ‘swagger’ folder.
Installing Swagger UI on a WebSphere Server
- Open the WebSphere Admin Console.
- Click on Applications->New Application in the left side menu.
- Click New Enterprise Application.
- When asked for the path to the new application, browse to select the swagger.war file that was created in the ‘swagger’ folder.
- Choose the default settings for the next screens, until the ‘Map virtual hosts for Web modules’ screen is displayed. In the ‘Map virtual hosts for Web modules’ screen, change the Virtual host value from ‘default_host’ to ‘client_host’ in the dropdown box.
Note: The use of client_host assumes you are using the default Cúram configuration. Select the appropriate virtual host if this is not the case.
- On the ‘Map context roots for Web Modules’ screen, enter ‘/swagger’ for the value for Context Root.
- Choose the default settings for the rest of the installation. When the application has been successfully installed, ensure you save the updates.
- Go to Applications -> Application Types –>WebSphere Enterprise Applications in the left side menu.
- Select the checkbox beside the Swagger application, and click the ‘start’ button.
- Login to the Cúram application by opening a browser and accessing https://<
hostname>:<9044>/Rest/logon.jsp. This creates an LTPA cookie, which allows you to access the REST APIs through the Swagger UI tool.
- Using the same browser access the Swagger UI tool at https://<
- Note: The Swagger UI tool is using the same hostname and port as the Cúram application. This avoids any CORS (cross-origin resource sharing) issues. For any further information on CORS, please refer to the Swagger UI documentation.
- Click on any tag name to expand the list of resources that have this tag.
Figure 1: Expanding a tag name, in this case the ‘Person’ tag name, shows a list of resources</li>
- Click on any resource, e.g. /v1/persons, to show all details about the resource and its parameters. There will also be an option to try out this resource.Figure 2: Expanding a resource gives detailed information about that resource.
- Click ‘Try It Out’ to see details about the request and the response will be displayed.
Using Swagger UI
All resources for the API are now viewable in the Swagger UI tool. They are grouped together based on the tags that they have been configured with.