users@jersey.java.net

[Jersey] generating user-readable documentation from Jersey resources

From: <azadbolour_at_bolour.com>
Date: Fri, 22 Apr 2011 00:02:02 +0000 (GMT)

Hi,

Is there a recommended way of generating human-readable documentation
for a set of Jersey resources? I have seen the WADL samples. But it
appears that WADL was designed for machine-consumption.

What I am looking for is to generate documentation that is perhaps more
human friendly for client programmers to let them know the structure of
the expected request and response messages in the application.

Specifically: A set of Jersey resources receive requests and send
responses in the body of http messages. The payloads in the messages
are XML representations of POJOs or collections of POJOs, and the POJOs
are marked with @XmlRootElement annotations. This is all there is to
begin with - no source XSD or other descriptions.

What is a good way of going about creating user-readable documentation
in this scenario, so that users get detailed information about the
structure of the requests and responses expected by the Jersey
resources?

If WADL is all there is, how can WADL generation be configured to
produce something like an XSD for the payloads of each request and
response from just the resources and the annotated POJOs?

Many thanks.

Azad