users@jersey.java.net

[Jersey] Re: Automatic documentation tool?

From: Matthieu Heimer <matt.heimer_at_osdev.org>
Date: Thu, 8 Aug 2013 02:13:07 -0500

JSON doesn't have an adopted schema yet so there isn't anything being
generated at build time that can be converted into docs with POJO JSON
mapping beyond the resource structure and methods. If you went with
JAXB mapping you'll get XML schemas which you could do some XSLT on.
You could also look at http://fromage.github.io/jax-doclets/ and
http://enunciate.codehaus.org/ but I don't know if either handles POJO
mapping. What you could do is enable extended WADL generation and
JavaDocs some JSON examples in your code and then do XSLT on the
extended WADL.

You could probably do it with annotation processing but it'd be really
specific to Jackson or whatever mapping rules and notation you are
using. You'll probably get what you are looking for some time after
there is a final standard for JSON binding.

On Wed, Aug 7, 2013 at 3:51 PM, Robert DiFalco <robert.difalco_at_gmail.com> wrote:
> How does that help? Is a wadl automatically generated from source that
> defines the schema of all the JSON beans?
>
>
> On Wed, Aug 7, 2013 at 12:58 PM, Matthieu Heimer <matt.heimer_at_osdev.org>
> wrote:
>>
>> You could look at one of the WADL to HTML tools. http://wadl.java.net/
>>
>> On Wed, Aug 7, 2013 at 1:35 PM, Robert DiFalco <robert.difalco_at_gmail.com>
>> wrote:
>> > Most everything I have looked at has either required me to double
>> > annotate
>> > stuff, add more data, or shows only minimal information.
>> >
>> > If seems to me that if I use POJO java beans for all my return values,
>> > path
>> > params, and query params and if the Resources and Beans are well
>> > javadoc'd
>> > that there should be a tool that can auto-generate very good
>> > documentation
>> > showing all the JSON as well as the resource paths and methods. This
>> > should
>> > be able to just run as a maven task scraping the annotations and parsing
>> > the
>> > beans to assemble JSON.
>> >
>> > Does anyone know if a tool like this exists?
>> >
>> > Thanks!
>> >
>> >
>
>