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.