Digging a little further, it looks like I can get my javadoc comments into the wadl using the extended-wadl as described here:
http://wikis.sun.com/display/Jersey/HowToConfigureExtendedWADL
With that and an XSLT stylesheet, I should be able to get what I am looking for.
I'll check back if that turns out not to be the case.
Thanks.
--Tim
On Jan 13, 2011, at 1:51 PM, Tim McNerney wrote:
> 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
>