It would be nice if there was an example of this that did not depend on
maven.
On Thu, Jan 13, 2011 at 5:41 PM, Tim McNerney <mumbly_at_gmail.com> wrote:
> 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
> >
>
>