Sounds about right to me. Exactly what i was looking for.
On Fri, Feb 6, 2009 at 6:21 AM, Marc Hadley <Marc.Hadley_at_sun.com> wrote:
> On Feb 5, 2009, at 7:59 PM, Martin Grotzke wrote:
>
> 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.
>>
>> Sounds right to me.
>
> Marc.
>
>
> 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/
>>>
>>>
>>>
>>>
>>
> ---
> Marc Hadley <marc.hadley at sun.com>
> CTO Office, Sun Microsystems.
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>
>