CXF – Missing WADL method parameter element types with JSON JAX-RS services

If you’re using JSON to exchange data with your CXF JAX-RS service clients you might find your out-of-the-box WADL file a little light on detail.

WADL (Web Application Description Language) files are an excellent way of making our REST services self-describing. The structured list of data types and endpoints, when used with general purpose client applications like SoapUI, let us drive our lightweight XML over HTTP services with much the same point-and-click convenience with which we can drive our meatier SOAP ones.

And, if you’re working code-first with JAX-RS and using Apache CXF as your provider, you’ll get a fully functional WADL file for free for your XML over HTTP services.

If, on the other hand, your doing JSON over HTTP, you’ll have a little bit of extra work to do.

The code for this example is available on GitHub

Following a few comments from people struggling to get this example to work, I’ve also uploaded a runnable containerised version to Docker Hub.

Waddling with XML

By way of a simple example, here’s a JAX-RS annotated interface for a mortgage payment calculator service:-

@Path("/")
public interface MortgageCalculator {

    @POST
    @Consumes(MediaType.APPLICATION_XML)
    @Path("/payments")
    Float calculatePayment(MortgageDetails dtls);
}

This service takes the total mortgaged property value, the deposit value, the term and the associated interest rate and returns an indicative monthly payment. Since these parameters don’t really lend themselves to a URL path, though we could accept them as query parameters on an HTTP GET, for this example we’ll instead take them in an HTTP POST request parameter matching the MortgageDetails value object-

@XmlRootElement
public class MortgageDetails {

    private Float interestRate;
    private Integer totalAmount;
    private Integer depositAmount;
    private Integer termInYears;

    public MortgageDetails() {
    }

    // Getters and Setters
}

Deploying this service via CXF with the following Spring configuration:-

<jaxrs:server id="cxfMortgageCalculatorService" address="/">
    <jaxrs:serviceBeans>
        <ref bean="mortgageCalculator" />
    </jaxrs:serviceBeans>
</jaxrs:server>

Gives us a rather nifty WADL file when we stick ?_wadl on a request to our application (e.g. http://localhost:8080/mortgage-calculator?_wadl):-

<application xmlns="http://wadl.dev.java.net/2009/02"
             xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:prefix1="https://devsumo.com/mortgagecalculator">

    <grammars>
    …
        <xs:complexType name="mortgageDetails">
            <xs:sequence>
                <xs:element minOccurs="0" name="depositAmount" 
                        type="xs:int"/>
                <xs:element minOccurs="0" name="interestRate" 
                        type="xs:float"/>
                <xs:element minOccurs="0" name="termInYears" 
                        type="xs:int"/>
                <xs:element minOccurs="0" name="totalAmount" 
                        type="xs:int"/>
            </xs:sequence>
        </xs:complexType>
        …
    </grammars>

    <resources base="http://localhost:8080/mortgage-calculator/">
        <resource path="/">
            <resource path="payments">
                <method name="POST">
                    <request>
                        <representation mediaType="application/xml"
                                element="prefix1:mortgageDetails"/>
                    </request>
                    …
                </method>
            </resource>
        </resource>
    </resources>
</application>

And we get this completely for free with recent versions of CXF 2.x, though with CXF 3 we need an extra Maven dependency as the WADL generator has been moved out of the cxf-rt-frontend-jaxrs package and into the, admittedly more meaningfully modular, cxf-rt-rs-service-description package instead.

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description</artifactId>
    <version>3.0.3</version>
</dependency>

The highlighted element setting in the <representation/> element allows SoapUI or other dynamic clients to auto-generate a template request body for us, which makes testing and onboarding services like this pretty slick:-

Waddling with JSON

If we change our request parameter type to JSON though:-

@Path("/")
public interface MortgageCalculator {

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Path("/payments")
    Float calculatePayment(MortgageDetails dtls);
}

Then our WADL comes up short:-

<method name="POST">
    <request>
        <representation mediaType="application/json"/>
    </request>
    …
</method>

Point SoapUI at this WADL and the “Re-create a default representation from the schema” button will be disabled and you’re kinda on your own.

CXF’s JSON handling piggy-backs on JAXB but the problem here is that the default configuration for its WadlGenerator class doesn’t automatically link JSON to the JAXB generated schema. In order to enable it we need to add the WadlGenerator to our Spring beans and tweak its configuration:-

<bean id="wadlGenerator"
      class="org.apache.cxf.jaxrs.model.wadl.WadlGenerator">
    <property name="linkJsonToXmlSchema" value="true" />
</bean>

<jaxrs:server id="cxfMortgageCalculatorService" address="/">
    <jaxrs:serviceBeans>
        <ref bean="mortgageCalculator" />
    </jaxrs:serviceBeans>
    <jaxrs:extensionMappings>
        <entry key="json" value="application/json" />
    </jaxrs:extensionMappings>
    <jaxrs:providers>
        <ref bean="wadlGenerator" />
    </jaxrs:providers>
</jaxrs:server>

This gets our WADL back on track:-

<method name="POST">
    <request>
        <representation mediaType="application/json"
                        element="prefix1:mortgageDetails"/>
    </request>
    …
</method>

And SoapUI can once more generate a default payload for us:-

Waddling with JSON (redux)

Submitting this request though results in an error:-

HTTP/1.1 415 Unsupported Media Type

And the following appears in our server log file:-

SEVERE: No message body reader has been found for class
com.devsumo. mortgagecalculator.MortgageDetails,
ContentType: application/json

Simply setting a @Produces or @Consumes to APPLICATION_JSON on a JAX-RS interface method isn’t quite enough to get JSON flowing through CXF. There are a couple of extra steps required.

First up we need to add a JSON provider to our build. CXF supports either Jettison or Jackson. For this example we’ll go with Jettison:-

<dependency>
    <groupId>org.codehaus.jettison</groupId>
    <artifactId>jettison</artifactId>
    <version>1.3.5</version>
</dependency>

And we need to add CXF’s Jettison JSONProvider to our <jaxrs:providers/> list:-

<bean id="jsonProvider"
      class="org.apache.cxf.jaxrs.provider.json.JSONProvider">
    <property name="supportUnwrapped" value="true"/>
    <property name="dropRootElement" value="true"/>
    <property name="namespaceMap">
        <map>
            <entry key="https://devsumo.com/mortgagecalculator" 
                   value="mort"/>
        </map>
    </property>
</bean>

<jaxrs:server id="cxfMortgageCalculatorService" address="/">
    <jaxrs:serviceBeans>
        <ref bean="mortgageCalculator" />
    </jaxrs:serviceBeans>
    <jaxrs:extensionMappings>
        <entry key="json" value="application/json" />
    </jaxrs:extensionMappings>
    <jaxrs:providers>
        <ref bean="wadlGenerator" />
        <ref bean="jsonProvider"/>
    </jaxrs:providers>
</jaxrs:server>

JSONProvider offers a variety of options to control how JSON is marshalled on our behalf – the above minimal options make it friendly with the format generated by SoapUI.