Custom Jersey WADL generation

I had a situation where the auto generated WADL did not match with my Rest services.
The first difference was that the response is presented as an object instead of a collection of objects and the second one is that it could not handle JSONWithPadding as response.  Because I use this WADL in my Rest client generation, I need to fix these issues.

Lucky for me, Jersey JAX-RS allows us to provide the necessary WADL input files so the generated WADL matches with the Rest services.

To make this happen I did the following steps.

First I extended the WadlGeneratorConfig class in which I defined the following properties applicationDocsStream, grammarsStream,  resourceDocStream. These vars point to the xml files which will be used in the WADL generation.

We need to add the following init param com.sun.jersey.config.property.WadlGeneratorConfig to the Jersey servlet. This init param points to your WadlGeneratorConfig class

The first file is the application-doc.xml ( located in my src folder ),  this will be used for the Title and high level description of your Rest service.

<applicationdocs targetnamespace="http://research.sun.com/wadl/2006/10">
 <doc title="Oracle HR Demo API" xml:lang="en"> This is a paragraph that is added to the start of the generated application.wadl </doc>
</applicationdocs>

Next is the application-grammars.xml  ( located in my src folder )  this file contains the location of your own XML schema which contains all our XML Elements and Complextypes.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<grammars xmlns="http://wadl.dev.java.net/2009/02"     xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xi="http://www.w3.org/1999/XML/xinclude">
   <include href="../xsd/schema.xsd" />
</grammars>

Add the schema.xsd with the right definitions to the xsd folder located in the web folder of the web application.

The last file is the resourcedoc.xml, this file will be generated by the Maven javadoc plugin.

To generate the content of this file we need to add some javadoc annotations to our Rest Operation methods
For example the response.representation.200.qname annotation points to the employees element (schema.xsd).

Also the response.representation.200.example annotation points to an example object.

Add the Maven JavaDoc plugin with com.sun.jersey.wadl.resourcedoc.ResourceDoclet to your project pom and generate the resourcedoc.xml

Example of a resourcedoc.xml

Startup your Webapp and now the WADL looks like this

Here is my github demo project.