From: Tim McNerney <mumbly_at_gmail.com>
Date: Thu, 13 Jan 2011 08:54:02 -0800

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