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.
About this task
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. You 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. You can then return the JAXB model for clients to consume.
Procedure
- You can inject the Application subclass that contains all your resource classes. Then you can pass in the classes to the WADLGenerator to generate all your classes.
- Return the org.apache.wink.common.model.wadl.Application class, which is a JAXB annotated object. The JAX-RS MessageBodyWriter for JAXB annotated types are used to serialize the WADL document to the client.
Example
@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 if you want to add additional information */
return wadlAppDoc;
}
}