users@jersey.java.net

[Jersey] Re: Any Facility for Generating API Documentation for End Users?

From: Tim McNerney <mumbly_at_gmail.com>
Date: Thu, 13 Jan 2011 13:51:46 -0800

Unless I'm misunderstanding what you are talking about, this method doesn't give you any ability to document the calls and parameters. The trick as I see it is being able to pull the content of the javadoc to so that you have actual enduser documentation instead of just a canonical list of API calls with their parameters. Not that this isn't helpful, but would still be only a starting point for an enduser. So basically, one way of getting what I'm looking for would be "javaodc + wadl + xsl => html".

I suppose if the Jersey WADL generation code could inline the javadoc comments for the classes and parameters, you could get there with XSLT postprocessing.

--Tim

On Jan 13, 2011, at 1:17 PM, Christopher Piggott wrote:

> I generally use the WADLs for this, and what I did was to tie in a
> copy of the stylesheet that you can find here (and elsewhere):
>
> http://lists.w3.org/Archives/Public/public-web-http-desc/2010Jan/0001.html
>
> I also wrote one custom wadl generator that spits out the wadl in the
> DokuShare wiki markup format. I access http://server/wadl/doku and
> it just comes out in a format I can cut/paste.
>
> The only problem is that my objects are annotated beans that did NOT
> get generated by jxc. I don't have a schema. So my WADL doesn't
> properly document all the return types.
>
> If you have a good extended wadl, though, the xsl way isn't bad. The
> xsl itself is pretty complicated, though.
>
> Hope that helps.
>
> --Chris
>
>
> On Thu, Jan 13, 2011 at 11:54 AM, Tim McNerney <mumbly_at_gmail.com> wrote:
>> I've been rolling my own API documentation on a wiki for an app, but realized that most (though not all) of the info that I wanted in that document already existed in the application WADL combined with the javadoc. So I was wondering if anyone had put together a javadoc like system that would generate an API Doc for JAX-RS services? It seems like something which would already exist.
>>
>> So if you had a class that looked like:
>>
>> @Path("/containers")
>> @Produces("application/xml")
>> public class ContainersResource {
>>
>> /**
>> * Get a container identified by name.
>> *
>> * @param container name of the container
>> * @return instance of the container if it exists
>> */
>> @Path("{containername}")
>> public Container getContainer(@PathParam("containername") String container) {
>> return containerService.findByName(container);
>> }
>>
>> /**
>> * Return a list of containers matching the given status. Return no more than max entries with an offset of
>> * start using the standard sorting.
>> *
>> * @param status empty, full, unknown
>> * @param start offset into the list
>> * @param max max number of containers returned
>> * @return a container list
>> */
>> @GET
>> public Containers getContainers(@QueryParam("status") @DefaultValue("empty") String status,
>> @QueryParam("start") @DefaultValue("0") int start,
>> @QueryParam("max") @DefaultValue("10") int max) {
>> return containerService.findByStatus(start, max, status);
>> }
>> }
>>
>> You might generate:
>>
>> + /baskets
>> - /containers
>> DESCRIPTION: Return a list of containers matching the given status. Return no more than max entries with an offset of start using the standard sorting.
>> RETURNS: [application/xml] a container list
>> PARAMS:
>> * status - [String/"empty"] - empty, full, unknown
>> * start - [int/0] - offset into the list
>> * max - [int/10] - max number of containers returned
>> - /<containername>
>> DESCRIPTION: Get a container identified by name.
>> RETURNS: [application/xml] instance of the container if it exists
>> VALS:
>> * containername - [String] - name of the container
>> + /hutch
>>
>> Apologies for the ASCII interface, but I'm sure you've all seen enough REST API Docs to imagine what you'd end up with.
>>
>> Anyway, curious if Jersey, some Jersey related addon or some other JAX-RS implementation supports this type feature and if not, whether you'd be amenable to me adding it to the Jira list.
>>
>> Thanks.
>>
>> --Tim