HowToConfigureExtendedWADL

This page describes how you can get an extended WADL from your REST app. It aligns mostly with the extended-wadl-webapp sample and uses these features:

Add additional doc tags to the WADL
Create JAXB beans from xsd - you might also create the schema from your beans
Add the grammars element that includes the xsd file from which JAXB beans were generated to the WADL
Add javadoc from your resource classes to the WADL, using most of the supported javadoc tags

For getting the extended WADL as described above these things have to be done:

Configure the maven-jaxb-plugin to create JAXB beans from xsd - this is described here just to describe what's done in the sample.
Add the application-doc.xml and application-grammars.xml to the build classpath
Configure the maven-javadoc-plugin with the ResourceDoclet provided by the wadl-resourcedoc-doclet artifact to create the resource-doc.xml.
Create a subclass of WadlGeneratorConfig that defines/configures the WadlGenerators to use
Specify your custom WadlGeneratorConfig in the web.xml as the WadlGeneratorConfig

Create JAXB beans from xsd

This asumes that you have already defined your schema (xsd) from which you want to generate your JAXB beans. In the sample project this schema.xsd is used.

For generating JAXB beans from your xsd file you must configure the maven-jaxb-plugin in the build/plugins section of your pom.xml:

<plugin>
    <groupId>com.sun.tools.xjc.maven2</groupId>
    <artifactId>maven-jaxb-plugin</artifactId>
    <version>1.1</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <generatePackage>com.sun.jersey.samples.extendedwadl.model</generatePackage>
        <schemaDirectory>src/main/xsd</schemaDirectory>
        <includeSchemas>
            <includeSchema>**/*.xsd</includeSchema>
        </includeSchemas>
        <extension>true</extension>
        <strict>false</strict>
        <verbose>true</verbose>
    </configuration>
</plugin>

Add the `application-doc.xml` and `application-grammars.xml` to the build classpath

For maven you must add these resources to the build element in your pom.xml:

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <filtering>false</filtering>
    </resource>
</resources>

Configure the maven-javadoc-plugin to create the resource-doc.xml

Add the following xml (adapted to your needs) to the build/plugins section of your pom.xml. This is an example taken from the extended-wadl-webapp sample.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <phase>compile</phase>
        </execution>
    </executions>

    <configuration>

        <encoding>UTF-8</encoding>
        <verbose>false</verbose>
        <show>public</show>
        <subpackages>com.sun.jersey.samples.generatewadl.resources</subpackages>

        <doclet>com.sun.jersey.wadl.resourcedoc.ResourceDoclet</doclet>
        <docletArtifacts>
            <docletArtifact>
                <groupId>com.sun.jersey.contribs</groupId>
                <artifactId>wadl-resourcedoc-doclet</artifactId>
                <version>${jersey-release-version}</version>
            </docletArtifact>
            <!--
                Also specify jersey and xerces as doclet artifacts as the ResourceDoclet
                uses classes provided by them to generate the resourcedoc.
             -->
            <docletArtifact>
                <groupId>com.sun.jersey</groupId>
                <artifactId>jersey-server</artifactId>
                <version>${jersey-release-version}</version>
            </docletArtifact>
            <docletArtifact>
                <groupId>xerces</groupId>
                <artifactId>xercesImpl</artifactId>
                <version>2.6.1</version>
            </docletArtifact>
        </docletArtifacts>
        <additionalparam>-output ${project.build.outputDirectory}/resourcedoc.xml</additionalparam>

    </configuration>
</plugin>

You can also add additional implementations of DocProcessor to the ResourceDoclet, just change the additionalparam element to s.th. like

<additionalparam>-output ${project.build.outputDirectory}/resourcedoc.xml -processors com.sun.jersey.samples.extended.util.ExampleDocProcessor</additionalparam>

Of course you should specify your own DocProcessor implementations here (separate multiple by ":")
TODO Describe the DocProcessor feature

You should also be able to use the ResourceDoclet in some ant javadoc task. Something like this:

<javadoc access="public" classpathref="project.classpath">
	<fileset dir="${src.main}/java" defaultexcludes="yes">
		<include name="path/to/java/files" />
	</fileset>
	<doclet name="com.sun.jersey.wadl.resourcedoc.ResourceDoclet" pathref="project.classpath">
		<param name="-output" value="${build}/resourcedoc.xml" />
	</doclet>
</javadoc>

Make sure to include wadl-resourcedoc-doclet-<version>.jar, xerces-2.6.1.jar, and jersey libs to the doclet pathref classpath.

Configure the `WadlGenerators` to use

For this you must create a subclass of WadlGeneratorConfig like this:

public class SampleWadlGeneratorConfig extends WadlGeneratorConfig {

    @Override
    public List<WadlGeneratorDescription> configure() {
        return generator( WadlGeneratorApplicationDoc.class ) 
            .prop( "applicationDocsStream", "application-doc.xml" ) 
        .generator( WadlGeneratorGrammarsSupport.class ) 
            .prop( "grammarsStream", "application-grammars.xml" ) 
        .generator( WadlGeneratorResourceDocSupport.class ) 
            .prop( "resourceDocStream", "resourcedoc.xml" ) 
        .descriptions();
    }

}

Right now, there's still support for file based configuration including the classpath: notation.
Notice, that file based configuration as shown by the following example will be removed in future versions of jersey:

public class SampleWadlGeneratorConfig extends WadlGeneratorConfig {

    @Override
    public List<WadlGeneratorDescription> configure() {
        return generator( WadlGeneratorApplicationDoc.class )
            .prop( "applicationDocsFile", "classpath:/application-doc.xml" )
        .generator( WadlGeneratorGrammarsSupport.class )
            .prop( "grammarsFile", "classpath:/application-grammars.xml" )
        .generator( WadlGeneratorResourceDocSupport.class )
            .prop( "resourceDocFile", "classpath:/resourcedoc.xml" )
        .descriptions();
    }

}

Configure your custom `WadlGeneratorConfig` in the web.xml

To tell Jersey which WadlGenerators shall be used add the following init-param to the servlet element for Jersey in the web.xml:

<init-param>
    <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name>
    <param-value>com.sun.jersey.samples.extendedwadl.SampleWadlGeneratorConfig</param-value>
</init-param>

You're finished

Start your jersey REST app, GET the application.wadl (e.g. via curl http://localhost:8080/application.wadl) and check if the output looks like this: ExtendedWadlExample.

HowToConfigureExtendedWADL

Create JAXB beans from xsd

Add the application-doc.xml and application-grammars.xml to the build classpath

Configure the maven-javadoc-plugin to create the resource-doc.xml

Configure the WadlGenerators to use

Configure your custom WadlGeneratorConfig in the web.xml

You're finished

Labels

Add the `application-doc.xml` and `application-grammars.xml` to the build classpath

Configure the `WadlGenerators` to use

Configure your custom `WadlGeneratorConfig` in the web.xml