On Thu, 2009-02-05 at 12:29 -0700, Andrew Ochsner wrote:
> Also, here's another thing that's catching me. My resources accept
> JSON and I'm not using the Jettison JAXB->JSON marshalling. So my
> methods look like:
> @POST
> public Response createResource(JSONObject json) {
>
> }
>
> What I want to be able to do is add request params to the wadl for
> this method describing the json properties that are valid for this
> request. However, the ResourceDoclet only honors @param javadoc and
> only when the number of @param and actual paramters are the same. So
> maybe I need a different tag @request.param or something.
>
> Thoughts? Am happy to help contribute as I'm likely going to need
> this in one form or another.
Hmm, just thinking about the "correct" solution in terms of WADL.
AFAICS you want to document your request representation, not the
request. Therefore you should be able to add a wadl param element as
child to the representation element. The param would get a
style="plain", and you might use jsonpath (or whatever) in the path
attribute.
@Marc: if there's a better solution please step in.
Having this in mind, it seems that you would need javadoc tags like
@request.representation.param.foo.style plain
@request.representation.param.foo.path here.is.your[0].path
@request.representation.param.foo.doc Documentation for this property
(Note that I don't recommend a solution similar to the @response.param,
as in the meantime I think that this is not really nice: a bloated value
and it does not align with the @response.representation.{status}.*
stuff. Therefore I want to implement the "better" way for this.)
What do you think?
Cheers,
Martin
>
> Andy O
>
> On Thu, Feb 5, 2009 at 8:44 AM, Andrew Ochsner
> <aochsner_at_cs.stanford.edu> wrote:
> Okay, yeah turns out that each method was javadoc'ing the
> "guid" param except the last one which is what wins.
>
> Lesson here I guess is that really that all methods should
> javadoc it the same to get it in there.
>
> Thanks!
> Andy O
>
>
>
> On Wed, Feb 4, 2009 at 7:20 PM, Martin Grotzke
> <martin.grotzke_at_freiheit.com> wrote:
> Hi Andrew,
>
> the trick is to use the param in some resource method:
>
> @Singleton
> @Path("/devices/{guid}")
> public class DevicesResource {
> @GET
> public String echo( @PathParam( "guid" ) String
> guid ) {
> return guid;
> }
> }
>
> Without this, it doesn't show up in the wadl. Right
> now, the wadl param
> element attached to the resource is the wadl param
> that was found as
> param in some method.
>
> Therefore, it's enough for you to java-document the
> method param to get
> the wadl param documented.
>
> To be able to supply a resource wide param
> documentation like what I
> suggested (e.g. @pathparam.guid in your case, on class
> level) the code
> building the wadl would have to be refactored. This
> would also be
> required to have better support for resource params,
> e.g. when they are
> used as class fields - AFAICS those would get dropped
> now (that's why I
> couldn't produce the wadl param at first, I just used
> the path param as
> a field withing the resource class).
>
> I'll enter an issue for this (the next days).
>
> However, you should have a solution for now - at least
> I hope so :)
>
> Cheers,
> Martin
>
>
>
> On Wed, 2009-02-04 at 10:58 -0700, Andrew Ochsner
> wrote:
> > So, I'm using 1.0.1 right now...not sure if that
> matters...
> >
> > Have a class that looks similar to this:
> > @Path("devices/{guid}")
> > @Service
> > @Produces({ MediaType.APPLICATION_JSON })
> > @Consumes({ MediaType.APPLICATION_JSON })
> > public class DevicesResource {}...
> >
> >
> > And wadl section like this:
> > <ns2:resource
> >
> path="devices/{guid}"><ns2:doc><![CDATA[Comments
> > here]]></ns2:doc><ns2:param
> > type="xs:string" style="template"
> name="guid"
> >
> xmlns:xs="http://www.w3.org/2001/XMLSchema"/>....
> >
> > I'm using just the ResourceDoclet and
> WadlGeneratorResourceDocSupport.
> > See this behavior both when generating wadl at build
> time using my Ant
> > task as well as when generated at runtime
> >
> >
> > On Tue, Feb 3, 2009 at 9:46 PM, Martin Grotzke
> > <martin.grotzke_at_freiheit.com> wrote:
> > Hi Andrew,
> >
> > I just wanted implement the support for
> documentation of
> > resource wide
> > path params.
> >
> > However, when I set the @Path annotation on
> the resource class
> > to s.th.
> > like "/items/{someparam}" I don't see a
> param element for this
> > resource
> > in the generated wadl.
> >
> > Can you post your resource class?
> > How are you generating the wadl file?
> >
> > Cheers,
> > Martin
> >
> >
> >
> > On Tue, 2009-02-03 at 11:26 -0700, Andrew
> Ochsner wrote:
> >
> >
> > > So I have a resource whose path is
> > @Path(/resource/{selector}) When
> > > i generate wadl, it does insert a resource
> wide param
> > element. Is
> > > there any way (via javadoc or some other)
> to add a
> > description to that
> > > resource wide parameter?
> > >
> > > Andy o
> >
>
>
>
> --
> Martin Grotzke
> http://www.javakaffee.de/blog/
>
>
>