WAS v8.5 > End-to-end paths > Web services - RESTful services > Use WADL to generate service documentation > Step 4. Use WADL to generate service documentation.

Serving a WADL document for the resources

A developer might not want to expose the Web Application Description Language (WADL) document via an OPTIONS request to limit the amount of information a third party can gather about a service. By providing less information, security through obscurity may be achieved. By default, a WADL document can be requested for a particular resource by invoking an HTTP OPTIONS request for any Java API for RESTful Web Services (JAX-RS) URL. We can issue an OPTIONS request with most HTTP clients.

We can also build our own WADL document using the org.apache.wink.common.model.wadl.WADLGenerator. WADLGenerator builds a JAXB annotated object model so we can return it as an entity response in an @OPTIONS resource method. If you want a service document for all the classes in the application, we can use the WADLGenerator to create a WADL representation. The service document can help enhance the understanding.

In the following example, we can use the WADLGenerator to build a JAXB model of your resources. We can then return the JAXB model for clients to consume.

1. Use org.apache.wink.common.model.wadl.WADLGenerator to build your WADL document. The following example illustrates a basic resource with an OPTIONS request:

   @javax.ws.rs.Path("myexample")
   public class MyResource {
       @Context
       javax.ws.rs.core.Application app;
       
       @javax.ws.rs.OPTIONS
       @Produces("application/vnd.sun.wadl+xml")
       public org.apache.wink.common.model.wadl.Application getOptions() {
           org.apache.wink.common.model.wadl.Application wadlAppDoc = new WADLGenerator().generate("", app.getClasses());
           /* modify the  wadlAppDoc JAXB model to add additional information */
           return wadlAppDoc;
       }}

   We can inject the Application sub-class containing all your resource classes. Then we can pass in the classes to the WADLGenerator to generate all your classes.

2. Return the org.apache.wink.common.model.wadl.Application class, which is a JAXB annotated object. The JAX-RS MessageBodyWriter for JAXB annotated types will be used to serialize the WADL document to the client.

   @javax.ws.rs.Path("myexample")
   public class MyResource {
       @Context
       javax.ws.rs.core.Application app;
       
       @javax.ws.rs.OPTIONS
       @Produces("application/vnd.sun.wadl+xml")
       public org.apache.wink.common.model.wadl.Application getOptions() {
           org.apache.wink.common.model.wadl.Application wadlAppDoc = new WADLGenerator().generate("", app.getClasses());
           /* modify the  wadlAppDoc JAXB model to add additional information */
           return wadlAppDoc;
       }}

Results

You have built your WADL document using the WADLGenerator.

Related

Disable generation of WADL documents for HTTP OPTIONS requests

Reference:

Web services specifications and APIs

+

Search Tips   |   Advanced Search