So looking at this cause I need something today... Think it makes sense
just to reuse WadlParamType which formats @<request|response>.param {_at_name
id}{@style plain}{@type {
http://www.w3.org/2001/XMLSchema}string}{@doc (req)
unique id} rather than @<request|response>.param.<name>.style/type/doc/etc
Will submit what I get if it helps...shouldn't be too many changes
On Fri, Feb 6, 2009 at 9:01 AM, Andrew Ochsner <aochsner_at_cs.stanford.edu>wrote:
> 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
>>
>>
>