The Jersey framework has a built-in support for generating the WADL file for your JAX-RS applications. In this section, we will discuss the Jersey support for generating the WADL file from the JAX-RS resource classes.

Consider the following JAX-RS web service implementation. The REST resource used in this example exposes the APIs for reading the list of departments, creating a department, and editing a department identified by the ID:

//Imports are removed for brevity 
@Stateless 
@Path("departments") 
public class DepartmentResource{ 
 
    //Returns departments in the range specified via query params 
    @GET 
    @Produces("application/json") 
    public List<Department> findAllDepartments(@QueryParam("from")  
        Integer from, @QueryParam("to") Integer to) { 
        return findAllDepartmentEntities(from, to); 
    } 
 
    //Creates department with data present in the request body 
    @POST 
    @Consumes("application/json") 
    public void createDepartment(Department entity) { 
        createDepartmentEntity(entity); 
    } 
 
    //Edits department with data present in the request body 
    @PUT 
    @Path("{id}") 
    @Consumes("application/json") 
    public void editDepartment(@PathParam("id") Short id, 
        Department entity) { 
        editDepartmentEntity(entity); 
    } 
    
    //Rest of the implementation is removed for brevity 
} 

The Department class used in this example will look like the following:

//Other imports are removed for brevity 
import javax.xml.bind.annotation.XmlRootElement; 
@XmlRootElement 
public class Department implements Serializable { 
    private Short departmentId; 
    private String departmentName; 
    private Integer managerId; 
    private Short locationId; 
//Getters and setters for the attributes are removed for brevity 
} 

The WADL generation feature is enabled in the Jersey framework by default. For instance, when you deploy the preceding JAX-RS application to a web server, the Jersey framework automatically generates a WADL file for all the JAX-RS resource classes present in the application. The generated WADL file is accessible via the following URI:
http://<host>:<port>/<application-name>/<application-path>/application.wadl

The URI for accessing WADL for this example is as follows:
http://<host>:<port>/rest-chapter7-jaxrs2wadl/webresources/application.wadl

The JAX-RS annotations present on the resource class decide how the APIs need to be represented in the WADL.

Every unique @Path value present in the resource class results in a new <resource> element in the generated WADL. Following this rule, this example adds the findAllDepartments and createDepartment methods as children to a common resource element, whereas the editDepartment method uses a path parameter, due to which this method is added as a child to a separate resource. In a nutshell, multiple resource methods with different HTTP methods but sharing the same @Path value will have the same parent <resource> element.

Here is the WADL file generated by the Jersey framework for the DepartmentResource resource shown in the preceding code:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
    <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 2.21 2015-08-14 21:41:51"/>
    <doc xmlns:jersey="http://jersey.java.net/" jersey:hint="This is simplified WADL with user and core resources only. To get full WADL with extended resources use the query parameter detail. Link: http://localhost:15647/rest-chapter7-jaxrs2wadl/webresources/application.wadl?detail=true"/>
    <grammars>
        <include href="application.wadl/xsd0.xsd">
            <doc title="Generated" xml:lang="en"/>
        </include>
    </grammars>
    <resources base="http://localhost:15647/rest-chapter7-jaxrs2wadl/webresources/">
        <resource path="departments">
            <method id="createDepartment" name="POST">
                <request>
                    <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="department" mediaType="application/json"/>
                </request>
            </method>
            <method id="findAllDepartments" name="GET">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="from" style="query" type="xs:int" default="1"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="to" style="query" type="xs:int" default="100"/>
                </request>
                <response>
                    <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="department" mediaType="application/json"/>
                </response>
            </method>
            <resource path="{id}">
                <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="id" style="template" type="xs:short"/>
                <method id="findDepartment" name="GET">
                    <response>
                        <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="department" mediaType="application/json"/>
                    </response>
                </method>
                <method id="editDepartment" name="PUT">
                    <request>
                        <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="department" mediaType="application/json"/>
                    </request>
                </method>
            </resource>
        </resource>
    </resources>
</application>

If you want to disable the automatic generation of WADL in Jersey, configure jersey.config.server.wadl.disableWadl to true. This configuration parameter can be set in either of the following ways:

• By setting the init-param value, jersey.config.server.wadl.disableWadl, to true for the Jersey servlet (org.glassfish.jersey.servlet.ServletContainer) in web.xml
• By overriding javax.ws.rs.core.Application::getProperties() to return the map containing jersey.config.server.wadl.disableWadl=true as the property name and value

The default support for WADL in Jersey works for many use cases. However, it may fail to generate proper documentation in specific scenarios, as explained here:

• If the resource method returns the javax.ws.rs.core.Response object, Jersey will not be able to infer the HTTP response content and HTTP status codes returned by the method from the method signature
• Similarly, Jersey will not be able to identify the header parameters present in the Response object by just scanning through the method signature

The solution for the preceding scenario is to intercept the default WADL generation process and pass the necessary data about the return types. Jersey allows you to do so by extending org.glassfish.jersey.server.wadl.config.WadlGeneratorConfig.