JavaEE and Swagger: TomEE example

More and more applications are composed of REST services. In JavaEE land it means you develop and expose JAX-RS services.

Once developped and well tested with TomEE the first thing you will realize is that to make an API useful you need to document it. There are a lot of ways to do it but Swagger seems to be the trendy one and it is indeed a nice solution as we’ll see in this post.

For the purpose of this article we’ll start from this simple service:

@Transactional
@ApplicationScoped
@Path("users")
@Produces(MediaType.APPLICATION_JSON)
public class UserResource {
    @GET
    public UserPage getUsers(@QueryParam("number")
                             final int number,

                             @QueryParam("offset")
                             final int offset) {

        // ...
    }

    @GET
    @Path("{id}")
    public UserModel get(@PathParam("id") final long userId) {
        // ...
    }
}

This is a fully JavaEE (7 in this case) service returning user(s). To “expose” it with swagger we need to decorate it with @Api and we can document a bit more each method and parameters with a set of dedicated annotations like @ApiOperatoin or @ApiParam::

@Transactional
@ApplicationScoped
@Path("users")
@Produces(MediaType.APPLICATION_JSON)
@Api("user") // swagger tag
public class UserResource {
    @GET
    @ApiOperation(value = "Find users.") //swagger method description/comment
    public UserPage getUsers(@QueryParam("number")
                             @ApiParam(value = "page size", defaultValue = "20") // swagger param doc
                             @DefaultValue("20")
                             final int number,

                             @QueryParam("offset")
                             @ApiParam(value = "item offset", defaultValue = "0")
                             @DefaultValue("0")
                             final int offset) {
        // ...
    }

    @GET
    @Path("{id}")
    @ApiOperation(value = "Find a user by id.")
    public UserModel get(@PathParam("id") @ApiParam(value = "user id", required = true) final long userId) {
        // ...
    }
}

Sure it adds several annotations but then swagger will be able to generate either at build time with jaxrs-analyzer or at runtime like we’ll see the corresponding model.

Tip: of course you can also just write your model in YAML or JSON manually before having developped the service and just expose it with the same technique we’ll see now.

Once the model is computed swagger is able to expose it as JSON or YAML. Until here it is cool for machine to machine API validation but not very useful for API documentation which is intended for users first.

For that purpose you need to use another part of swagger which is swagger-ui which just reads the previous model and creates a GUI from it.

Let’s see how to set it up in a EE server – TomEE for us.

Dependencies

You only need swagger-jaxrs and swagger-ui to set it up:

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-jaxrs</artifactId>
  <version>1.5.3</version>
  <exclusions>
    <!-- API are useless since in javaee-api -->
    <exclusion>
      <groupId>javax.ws.rs</groupId>
      <artifactId>jsr311-api</artifactId>
    </exclusion>
    <exclusion>
      <groupId>javax.validation</groupId>
      <artifactId>validation-api</artifactId>
    </exclusion>
    <!-- not useful for the GUI -> only json for us -->
    <exclusion>
      <groupId>com.fasterxml.jackson.dataformat</groupId>
      <artifactId>jackson-dataformat-xml</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.fasterxml.jackson.datatype</groupId>
      <artifactId>jackson-datatype-joda</artifactId>
    </exclusion>
    <!-- we don't use reflections so no need of javassist -->
    <exclusion>
      <groupId>org.javassist</groupId>
      <artifactId>javassist</artifactId>
    </exclusion>
    <exclusion>
      <groupId>org.reflections</groupId>
      <artifactId>reflections</artifactId>
    </exclusion>
    <!-- we'll reuse the container one or add an impl as well to your app -->
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.webjars</groupId>
  <artifactId>swagger-ui</artifactId>
  <version>2.1.8-M1</version>
</dependency>

Swagger-ui is a webjars containing the UI and you can of course use any other frontend solution to get the javascript/css but webjars are a fast solution which fits very well a blog post :).

Swagger-jaxrs is the module bringing the stack needed to introspect the swagger annotations and create the model the UI needs. As you can see you can exclude a bunch of transitive dependencies we’ll not use and which can conflict with your application or container – or even just leak.

API metadata

We already saw you can add metadata (annotations) on your services but you can also add a title, version, … to your API and you need to add a base path (JAX-RS mapping) to let swagger be able to create correct URLs for your endpoints (keep in mind if you are exposed behind a proxy swagger can sometimes not guess the external endpoint).

To do so the easiest solution is to add the swagger servlet in your web.xml and set it up as init parameters:

<web-app version="3.1"          xmlns="http://xmlns.jcp.org/xml/ns/javaee"          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"          xsi:schemaLocation="           http://xmlns.jcp.org/xml/ns/javaee           http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd">

  <servlet>
    <servlet-name>swagger</servlet-name>
    <servlet-class>io.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class>
    <init-param>
      <param-name>api.version</param-name>
      <param-value>${project.version}</param-value>
    </init-param>
    <init-param>
      <param-name>swagger.api.basepath</param-name>
      <param-value>http://localhost:8080/app/api</param-value>
    </init-param>
    <init-param>
      <param-name>swagger.api.title</param-name>
      <param-value>My Awesome API</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

</web-app>

Notes:

• swagger basepath can be a full URL or partial one.
• here we used maven version for the API version and added the web.xml to be filtered thanks to the maven war plugin configuration. In practise the API version rarely follows the project version but it was mainly to remind you the build tool can still be central and used even if the configuration is in web.xml file.

Note: no need of any servlet mapping, servlet API is just used to initialized swagger internals – there are alternatives but they need code compared to this one.

JAX-RS integration

Once swagger-jaxrs is added to your project you can use the provided swagger ApiListingResource JAX-RS resource to expose the swagger model at /swagger URL. If your container and JAXRS application is configured to use scanning nothing needed to get it otherwise keep in mind to add it to the resources you expose.

Now adding swagger dependencies also adds jackson and its jaxrs providers. This means you can get conflicts if it is not the one you want. To avoid that – and for TomEE case – we’ll add a WEB-INF/openejb-jar.xml specifying we want to use Apache Johnzon as JAX-RS JSON provider:

<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar>
  <pojo-deployment class-name="jaxrs-application">
    <properties>
      # swagger brings back jackson*, maybe not what you want in your app so let's take the control over providers
      cxf.jaxrs.skip-provider-scanning = true

      # let's keep the default TomEE JSON provider (johnzon)
      cxf.jaxrs.providers = org.apache.johnzon.jaxrs.JohnzonProvider
    </properties>
  </pojo-deployment>
</openejb-jar>

Of course we could use jackson but if your application already uses johnzon specific features this allows to keep it and it doesn’t break swagger :).

Note: using JAX-RS integration supposes you use an Application subclass. if not you need to set up swagger to scan for resources or use CXF (Swagger2Feature) / Jersey / Spring integration.

Set it up the Swagger GUI

Finally to setup the swagger GUI we just need to add an index.jsp (or any other location if swagger will not be your home page) containing:

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<!DOCTYPE html>
<html>
<head>
    <title>Java WordPress API</title>
    	<link href='webjars/swagger-ui/2.1.8-M1/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
    	<link href='webjars/swagger-ui/2.1.8-M1/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
    	<link href='webjars/swagger-ui/2.1.8-M1/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    	<link href='webjars/swagger-ui/2.1.8-M1/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
    	<link href='webjars/swagger-ui/2.1.8-M1/css/screen.css' media='print' rel='stylesheet' type='text/css'/>
    <script src="webjars/swagger-ui/2.1.8-M1/lib/shred.bundle.js" type="text/javascript"></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/handlebars-2.0.0.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/underscore-min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/backbone-min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/swagger-client.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/swagger-ui.min.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/highlight.7.3.pack.js' type='text/javascript'></script>
    <script src='webjars/swagger-ui/2.1.8-M1/lib/marked.js' type='text/javascript'></script>
</head>

<body class="swagger-section">
<div id="message-bar" class="swagger-ui-wrap">&nbsp;</div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
<script type="text/javascript">
    $(function () {
        new SwaggerUi({
            url: '<%= application.getContextPath() %>/api/swagger',
            dom_id: 'swagger-ui-container',
            swaggerRequstHeaders: 'application/json', // if you don't want to use it add .json to the url
            sorter: 'alpha'
        }).load();
    });
</script>
</body>
</html>

All the work is done by SwaggerUi class provided by swagger-ui module. You see however we rely on JSP to set the context path dynamically which is a nice feature for web applications.

Side note: we suppose our JAX-RS application has an @ApplicationPath set to “api”.

Test Swagger UI

To test it I personally used tomee embedded maven plugin:

<plugin> <!-- mvn tomee-embedded:run to start testing against a real MySQL -->
  <groupId>org.apache.tomee.maven</groupId>
  <artifactId>tomee-embedded-maven-plugin</artifactId>
  <version>7.0.0-M1</version>
  <configuration>
    <context>/${project.artifactId}</context>
    <classpathAsWar>true</classpathAsWar>
  </configuration>
</plugin>

And just run:

mvn tomee-embedded:run

Then you can go in http://localhost:8080/app/ and you should see something like:

Want more content ? Keep up-to-date on my new blog

Or stay in touch on twitter @rmannibucau