Deploying Swagger-enabled endpoints with

WebSphere Liberty in AIX

Version 0.2




This document will help anyone who is developing REST APIs on AIX operating system
running on POWER servers. Here we will discuss on how to write simple JAX-RS based REST APIs
and deploy it in WebSphere Liberty Profile. We will also see more on the popular Swagger
Framework.

Overview

Web applications can be developed using multiple programming languages like Java, perl,
php, javascripts, python, ruby, scala etc. Out of these, we are going to focus only on Java based
web applications. Then when it comes to Java Web services development there are different
frameworks available. The popular ones are DropWizard, Jersey, Play, Restlet. In our examples
we will be using only Jersey which is a JAX-RS based implementation. JAX-RS (Java API for RESTful
Web Services) is an annotation based specification for developing and deploying web service
endpoints.

With the advent of API economy, most of the RESTful web services are adapting to
frameworks like Swagger for its rich feature sets like interactive documentation, client SDK
generation and easy discoverability of REST APIs by API management tools. Jersey framework is
supported by Swagger. We will show you ways how both can be integrated and deployed in
WebSphere Liberty profile server.

Requirements

To develop a swagger enabled REST API on AIX, the following dependencies need to be met,

1. WebSphere Application Server Liberty 16.0.0.2
a. This runtime can be downloaded from IBM website:
http://www-01.ibm.com/support/docview.wss?uid=swg24042163#LibertyJarAll
b. Along with this runtime package make sure IBM SDK 8 is downloaded and installed
as Java EE 7 features are dependent on it.
2. Maven – Java Build Tool
a. Get the Maven bundle from http://maven.apache.org. Un-tar it to a directory of choice and
include the “. /bin” directory to the PATH environment variable.

Creating a Simple REST Service

To develop a web application that can be packaged as “.war” (web archive) file and deploy
it in a servlet container like Tomcat, WebSphere Application Server, or WebSphere Liberty Profile,
follow the process,

1. “mvn” command helps us create the project structure for the new web application
based on the archetype id provided by the user. In our case, we will use “jersey-
quickstart-webapp” to create as the skeleton,

mvn archetype:generate \
-DarchetypeArtifactId=jersey-quickstart-webapp \
-DarchetypeGroupId=org.glassfish.jersey.archetypes \
-DinteractiveMode=false \
-DgroupId=com.example \
-DartifactId=simple-service-webapp \
-Dpackage=com.example \
-DarchetypeVersion=2.23.2

2. The project structure looks as follows,

a. Project build and management configuration is described in
the pom.xml located in the project root directory.
b. Project sources are located under src/main/java.
c. Project resources are located under src/main/resources.
d. Project web application files are located under src/main/webapp.
e. Web.xml deployment descriptor is placed under src/main/webapp/WEB-
INF directory

3. To get a “war” file out of this project, run the following command,
mvn clean package

4. The war file will be found under: ./simple-service-webapp/target/simple-service-
webapp.war
5. Let’s try to peek into the source file “./src/main/java/com/example/
MyResource.java” created in the earlier step,



a. You will find the “@Path” annotation which specifies the uri path to access
the given class “MyResource”.
b. One of the method “getIt” will accept all the GET request coming from the
clients and its highlighted by the “@GET” annotation. This method is
simple enough it returns a fixed string to the caller.
6. Identify the base route to access the above servlet by looking into the web.xml file
found under ./src/main/webapp/WEB-INF/web.xml,
a. Under “servlet-mapping” tag you will find the “url-pattern” tag which show
all the URL of this pattern will be routed to the servlet name “Jersey Web
Application”.
7. Now let’s deploy it inside “WebSphere Liberty Profile(WLP)” and make it
accessible over internet using a URL,
a. Copy the generated “war” file, created in Step 3 to {WLP}/
usr/servers/defaultServer/dropins/ directory.
b. Restart the WLP server by {WLP}/bin/server stop/start.
8. After the WLP server is restarted, the web application goes online and will be
made accessible via the URL http://example.ibm.com:9080/simple-service-
webapp/webapi/myresource and you can see the pre-defined string returned by
“getIt” function in the browser.
9. Let’s try to add a simple REST service which greets the user given a user name as
part of the URL path by adding the following code to “MyResource.java” file,

 10. Repeat Step 3 to redeploy the modified web application. The API can be now
accessible as,
http://example.ibm.com:9080/simple-service-
webapp/webapi/myresource/hello/joe
By accessing the URL, you will get the hello message with the user name “joe”
printed in the webpage.

Swagger Overview

Swagger is a open source project created to standardize the way REST APIs are best
described and documented. The swagger specification defines a set of files(swagger.json) to
describe a RESTful API. There are two major sub-project under Swagger,

1. Swagger-ui (http://swagger.io/swagger-ui/):
a. This utility is a web based tool used to display the API and its
documentation based on the swagger definition files defined by the API
provider in a user friendly way.
b. It also provides a way to the end users to try out the API right from the
web interface even before its integrated to their application.
2. Swagger-codegen (http://swagger.io/swagger-codegen/):
a. This command line utility is capable of generating client library code
based on the swagger specification file in many popular languages so that
the REST APIs can be easily consumed by end users.
b. It is capable of generating the server stub code in many popular web
frameworks based on a swagger definition file. API developers can insert
the business core logic into the templated generated by the tool.


More information related to Swagger specification can be found in
http://swagger.io/specification/.

Adding Swagger Definitions

Before publishing the created REST API, proper documentation is required in a
standardized way. Swagger has standardized the REST API documentation & also made it easier
for getting it discovered inside API Managers.

So it’s time to add a Swagger compliant documentation to our Web Service by following
the steps,

1. The annotations are added to the class names and method names as follows,



2. The swagger annotations will be resolved only after you add the following
dependencies inside the base directory’s pom.xml file,

<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.9</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>

3. Next step to get swagger definitions ready for our simple rest API is to add the
Bootstrap code (Bootstrap.java) to our web application under the package
“com.ibm.helpers”,



4. In order to make sure the swagger code gets initialized make the necessary
changes to the web.xml found under ./src/main/webapp/WEB-INF/ directory as
follows,



5. The project should be rebuilt using “mvn package” and the generated “.war” file
should be redeployed to WebSphere Liberty Profile server.
6. Now along with the web service, a swagger definition file is also made available
under the URL:
http://example.ibm.com:9080/simple-service-webapp/webapi/swagger.json

Integration with WebSphere’s ApiDiscovery Feature

ApiDiscovery is a feature of WebSphere Liberty Profile that can be installed & loaded
separately to the existing WebSphere Liberty Profile server runtime by executing the following
command after getting into the WebSphere Liberty Profile install directory,

bin/installUtility install apiDiscovery-1.0

To make this feature available to the server configuration add the following line under
the featureManager tag to the server.xml,

<feature>apiDiscovery-1.0</feature>

Here is a snapshot of the server.xml file after the change,

After enabling this feature, you can access the following URL:
https://example.ibm.com:9443/ibm/api/explorer


To include the web applications discoverable, add the following line in server.xml,



Now the Swagger UI for the newly created API is seen as follows,

This is the type of UI that will be used by Application developer who want to use the REST
Api exposed by your organization. The UI gives them the option to interact by providing them
“Try it out” button right from the documentation page.


Reference:

1. https://jersey.java.net/
2. http://swagger.io/
3. https://maven.apache.org/download.cgi
4. https://developer.ibm.com/wasdev/downloads/liberty-profile-using-non-eclipse-
environments/