Network Deployment (Distributed operating systems), v8.0 > End-to-end paths > Web services - RESTful services > Use WADL to generate service documentation > 4. Use WADL to generate service documentation.

Serving a WADL document for your 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.

You can also build your own WADL document by using the org.apache.wink.common.model.wadl.WADLGenerator. WADLGenerator builds a Java Architecture for XML Binding (JAXB) annotated object model so you can easily return it as an entity response in an @OPTIONS resource method. If you want a service document for all the classes in your application, you can use the WADLGenerator to create a WADL representation. The service document can help enhance the understanding.

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

Procedure

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 that contains all your resource classes. Then you 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.
Disable generation of WADL documents for HTTP OPTIONS requests
Use WADL to generate service documentation

Related

Web services specifications and APIs

+

Search Tips   |   Advanced Search