The current extended WADL support is based on custom Javadoc tags:
http://wikis.sun.com/display/Jersey/WADL
Its very handy but it suffers from a couple of problems:
(i) Its quite involved to set up
(ii) Its not very internationalization (I18N) friendly.
The current support can be split into two functional areas:
(a) Additional runtime information
(b) Documentation
It seems to me that for (a) we could fix (i) by making the following Javadoc tags (see
http://wikis.sun.com/display/Jersey/SupportedJavadocTagsForExtendedWADL) be annotations instead:
@request.representation.qname
@request.representation.mediaType
@response.param
@response.representation.XXX.qname
@response.representation.XXX.mediaType
E.g. to provide additional metadata about a set of possible responses produced by a method you could add the following annotation:
@WadlResponses({
@WadlResponse(status=200, mediaType="application/foo+xml", entity=Foo.class),
@WadlResponse(status=400, mediaType="application/error+xml", name="error", namespace="http//example.com/errors")
})
As an aside it looks like one can determine the QName of a JAXB annotated class at runtime so the first @WadlResponse should be implementable.
Using annotations for this would remove the need for addition steps in the build and greatly simplify things IMO.
For (b) I really like the re-use of Javadoc but looking at the I18N tools out there it seems like most (if not all) are based on property files in resource bundles. We could address (ii) by supporting property files that hold the additional documentation. We could define some kind of method->property name mapping so that alternate localizations can be included with an app and selected at runtime using the value of the HTTP Accept-Language header. I think this would also address (i) since the property files can easily be included when building the code but it would lose the connection to Javadoc unless we offered some doclet that would generate the initial property files from existing javadoc.
What do folks think ?
Thanks,
Marc.