When you're in the business of creating Java Web Services today, be it JAX-WS or JAX-RS, one of the difficult things to get right is actually documenting the entities from a API developer point of view, especially in the scenario where your model is the code.
The main problem comes to the fact that a JAXB annotated model doesn't map anything to the generated schema contracts (be it WSDL or WADL+XSD) and classes. This is understandable as Javadocs don't exist at runtime and there is no specific JAXB annotation that maps to the xs:annotation, xs:documentation and xs:appinfo schema elements. Various tools like enunciate and all provide some support to to compile time generation but from my point of view the generated wadl + schema (my main scenario) is not the same quality as is the runtime generated ones.
Can this be improved?
Some guys at the The Distributed Systems Group (DSG) of the Information Systems Institute at the Technical University of Vienna
certainly thought so and they forked the JAXB API project to add the Java annotations for xs:annotation, appinfo and documentation, modified the JAXB implementation library schema generator to enhance the produced xsd by mapping the annotations to schema elements and also (which seems was their primary objective
) added support for schema facets thus allowing you to express with annotations things like pattern facets, min/max etc.).
The project is hosted here
but there's a fork which is a bit easier to test
because they went around a bit the troublesome java endorsed directory classloading mechanism (needed because JAXB implementation classes are on a protected package within the JDK) (this might change in time).
All in all, it looks very promising as it works with JAX-RS and Jersey so, if they can unify the facets with the JSR-303 and JSR-349 annotations and also have it supported by the xjc binding compiler it would go a really long way in providing a much nicer API documentation (yes, yes, that's soooo 90'ies blah blah) and schemas but also declarative validation of service interfaces.
If you agree, point your browsers to the java.net JIRA and vote here
All in all a nice renaissance for services considering Jersey 2.0 is coming up and all the hypermedia API standards that are emerging.
On a tangent, I believe a fair chunk of JAXB schema generation code was written by Kohsuke
(of Hudson/Jenkins fame). If you dig in and read the code, your mind will warp, you have been warned.
Now, do your company a favor, make them buy OxygenXML
and generate some nice docos!