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.

Simple JAX-RS resource to match Can.JS defaults

Can.JS is a nice client side (javascript) library providing a MVC solution out of the box. The model is often backed by some JSON server and in Java(EE) case by JAX-RS.

Can.JS has a shortcut for CRUD models called ‘resource’ based on a default mapping. Let see how to implement it on a Java server side easily.

OpenJPA and Date JSON serialization

Following the trends, you can try to push your entities to the front layer of your application without any in between conversion. A common sample is to return an entity in a JAX-RS bean.

For instance:

Apache Johnzon: more configuration and TomEE integration

Apache Johnzon is an implementation of JSON-P specification but it also includes
a JSON java mapper and a JAX-RS provider.

First version was not very easy to configure (actually it was but it needed to extend
default implementation) but since 0.2-incubating it is designed to work out of the box.

It was done adding a new class: org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider
and a bunch of setters (+ lazy initialization of the mapper).

Here a sample to integrate it with TomEE resources.xml (but using Spring or any other configuration
model should work as well while setters are supported):

<Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider">
    ignores = com.foo.MyType,com.foo.MyOtherType
    accessMode = method
    supportHiddenAccess = true
    doCloseOnStreams = false
    version = 2
    skipNull = true
    skipEmptyArray = true
</Service>

Then to use it in TomEE just like it as usual in openejb-jar.xml:

<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
  <pojo-deployment class-name="jaxrs-application">
    <properties>
      cxf.jaxrs.providers = johnzon

      # this one is not mandatory but recommanded
      cxf.jaxrs.skip-provider-scanning = true
    </properties>
  </pojo-deployment>
</openejb-jar>

Side note: didn’t dig into it but using tomee service references ($refName)
you can even configure in resources.xml the Johnzon Mapper directly and just
set it (mapper attribute) in JohnzonProvider…but this is less intuitive then.

This way if default configuration (Pojo) doesn’t fit your need cause you use private constructors, field mapping etc… you can customize it pretty easily now.

Last but nice: default Johnzon provider is the one used out of the box in TomEE 2 for json serialization!