Regarding the responseClass parameter of @ApiOperation, is there a reason why the parameter is the fully qualified name of the class rather than Class<T>? Using the fully qualified name is a bit dangerous as it can fail on code refactoring and obviously is more error prone when it comes to typing (and it's a runtime error).
On another note, according to Tony, in order to set the return type to a List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". When I've tried that, I didn't get any model information for the API listing (using com.bar.Foo worked fine). Any suggestions as to why?
I imagine the second question might be the answer to the first. However, using some reflection magic, I'm fairly certain it can still be resolved by using a class rather than a string.
Also, I'd expect the @GET operations to use the return type of the method by default. If developers want to override it with the responseClass parameter, all the better, but since Response is not always used, the forced usage of the responseClass parameter can be somewhat redundant (a bit like having to say which HTTP method is used for the API call).
On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
> Regarding the responseClass parameter of @ApiOperation, is there a reason > why the parameter is the fully qualified name of the class rather than > Class<T>? > Using the fully qualified name is a bit dangerous as it can fail on code > refactoring and obviously is more error prone when it comes to typing (and > it's a runtime error).
> On another note, according to Tony, in order to set the return type to a > List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". > When I've tried that, I didn't get any model information for the API > listing (using com.bar.Foo worked fine). Any suggestions as to why?
> I imagine the second question might be the answer to the first. However, > using some reflection magic, I'm fairly certain it can still be resolved by > using a class rather than a string.
> Also, I'd expect the @GET operations to use the return type of the method > by default. If developers want to override it with the responseClass > parameter, all the better, but since Response is not always used, the > forced usage of the responseClass parameter can be somewhat redundant (a > bit like having to say which HTTP method is used for the API call).
On Thursday, July 5, 2012 12:16:20 AM UTC+3, tony tam wrote:
> Returning the class would probably be better for the responseClass, good > point. I'll see if that can be supported.
> If you're not getting models for List[com.bar.Foo] you probably found a > defect. I'll take a look at this.
> I think that picking the return type out of the method is pretty tricky > and that's why we made it explicit.
> Tony
> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>> Regarding the responseClass parameter of @ApiOperation, is there a reason >> why the parameter is the fully qualified name of the class rather than >> Class<T>? >> Using the fully qualified name is a bit dangerous as it can fail on code >> refactoring and obviously is more error prone when it comes to typing (and >> it's a runtime error).
>> On another note, according to Tony, in order to set the return type to a >> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >> When I've tried that, I didn't get any model information for the API >> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>> I imagine the second question might be the answer to the first. However, >> using some reflection magic, I'm fairly certain it can still be resolved by >> using a class rather than a string.
>> Also, I'd expect the @GET operations to use the return type of the method >> by default. If developers want to override it with the responseClass >> parameter, all the better, but since Response is not always used, the >> forced usage of the responseClass parameter can be somewhat redundant (a >> bit like having to say which HTTP method is used for the API call).
My understanding of it is that in the resources, people (including ourselves) will use the Response builder with JAX-RS, not just the return value--this lets you better control the response handling.
So if we look at the method signature and see that it returns java.ws.rs.core.Response, we will not get the entity type being marshalled in the response.
On Wednesday, July 4, 2012 9:49:25 PM UTC-7, Ron R wrote:
> Why do you say that picking the return type out of the method can be > tricky? Perhaps I can suggest a solution.
> On Thursday, July 5, 2012 12:16:20 AM UTC+3, tony tam wrote:
>> Returning the class would probably be better for the responseClass, good >> point. I'll see if that can be supported.
>> If you're not getting models for List[com.bar.Foo] you probably found a >> defect. I'll take a look at this.
>> I think that picking the return type out of the method is pretty tricky >> and that's why we made it explicit.
>> Tony
>> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>>> Regarding the responseClass parameter of @ApiOperation, is there a >>> reason why the parameter is the fully qualified name of the class rather >>> than Class<T>? >>> Using the fully qualified name is a bit dangerous as it can fail on code >>> refactoring and obviously is more error prone when it comes to typing (and >>> it's a runtime error).
>>> On another note, according to Tony, in order to set the return type to a >>> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >>> When I've tried that, I didn't get any model information for the API >>> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>>> I imagine the second question might be the answer to the first. However, >>> using some reflection magic, I'm fairly certain it can still be resolved by >>> using a class rather than a string.
>>> Also, I'd expect the @GET operations to use the return type of the >>> method by default. If developers want to override it with the responseClass >>> parameter, all the better, but since Response is not always used, the >>> forced usage of the responseClass parameter can be somewhat redundant (a >>> bit like having to say which HTTP method is used for the API call).
On Thu, Jul 5, 2012 at 9:48 AM, tony tam <feh...@gmail.com> wrote:
> My understanding of it is that in the resources, people (including
> ourselves) will use the Response builder with JAX-RS, not just the return
> value--this lets you better control the response handling.
> So if we look at the method signature and see that it returns
> java.ws.rs.core.Response, we will not get the entity type being marshalled
> in the response.
> Tony
> On Wednesday, July 4, 2012 9:49:25 PM UTC-7, Ron R wrote:
>> Why do you say that picking the return type out of the method can be
>> tricky? Perhaps I can suggest a solution.
>> On Thursday, July 5, 2012 12:16:20 AM UTC+3, tony tam wrote:
>>> Returning the class would probably be better for the responseClass, good
>>> point. I'll see if that can be supported.
>>> If you're not getting models for List[com.bar.Foo] you probably found a
>>> defect. I'll take a look at this.
>>> I think that picking the return type out of the method is pretty tricky
>>> and that's why we made it explicit.
>>> Tony
>>> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>>>> Regarding the responseClass parameter of @ApiOperation, is there a
>>>> reason why the parameter is the fully qualified name of the class rather
>>>> than Class<T>?
>>>> Using the fully qualified name is a bit dangerous as it can fail on
>>>> code refactoring and obviously is more error prone when it comes to typing
>>>> (and it's a runtime error).
>>>> On another note, according to Tony, in order to set the return type to
>>>> a List<Foo>, the responseClass parameter should be "List[com.bar.Foo]".
>>>> When I've tried that, I didn't get any model information for the API
>>>> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>>>> I imagine the second question might be the answer to the first.
>>>> However, using some reflection magic, I'm fairly certain it can still be
>>>> resolved by using a class rather than a string.
>>>> Also, I'd expect the @GET operations to use the return type of the
>>>> method by default. If developers want to override it with the responseClass
>>>> parameter, all the better, but since Response is not always used, the
>>>> forced usage of the responseClass parameter can be somewhat redundant (a
>>>> bit like having to say which HTTP method is used for the API call).
Fair enough. Since the Response isn't typed, there's no viable way of finding that out. I'm not familiar that much with Play, but I imagine it's similar.
On Tuesday, July 3, 2012 11:29:58 PM UTC+3, Ron R wrote:
> Regarding the responseClass parameter of @ApiOperation, is there a reason > why the parameter is the fully qualified name of the class rather than > Class<T>? > Using the fully qualified name is a bit dangerous as it can fail on code > refactoring and obviously is more error prone when it comes to typing (and > it's a runtime error).
> On another note, according to Tony, in order to set the return type to a > List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". > When I've tried that, I didn't get any model information for the API > listing (using com.bar.Foo worked fine). Any suggestions as to why?
> I imagine the second question might be the answer to the first. However, > using some reflection magic, I'm fairly certain it can still be resolved by > using a class rather than a string.
> Also, I'd expect the @GET operations to use the return type of the method > by default. If developers want to override it with the responseClass > parameter, all the better, but since Response is not always used, the > forced usage of the responseClass parameter can be somewhat redundant (a > bit like having to say which HTTP method is used for the API call).
I'm not sure of the best way to write unit tests for swagger though, if there's interest in having this in the main version then happy to write same if some guidance can be given. Seems as if the only code that tests this is in the swagger-jaxrs module, though perhaps some should be in swagger-core given that that's where the trait resides?
On Wednesday, 4 July 2012 17:16:20 UTC-4, tony tam wrote:
> Returning the class would probably be better for the responseClass, good > point. I'll see if that can be supported.
> If you're not getting models for List[com.bar.Foo] you probably found a > defect. I'll take a look at this.
> I think that picking the return type out of the method is pretty tricky > and that's why we made it explicit.
> Tony
> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>> Regarding the responseClass parameter of @ApiOperation, is there a reason >> why the parameter is the fully qualified name of the class rather than >> Class<T>? >> Using the fully qualified name is a bit dangerous as it can fail on code >> refactoring and obviously is more error prone when it comes to typing (and >> it's a runtime error).
>> On another note, according to Tony, in order to set the return type to a >> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >> When I've tried that, I didn't get any model information for the API >> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>> I imagine the second question might be the answer to the first. However, >> using some reflection magic, I'm fairly certain it can still be resolved by >> using a class rather than a string.
>> Also, I'd expect the @GET operations to use the return type of the method >> by default. If developers want to override it with the responseClass >> parameter, all the better, but since Response is not always used, the >> forced usage of the responseClass parameter can be somewhat redundant (a >> bit like having to say which HTTP method is used for the API call).
Hi Michael, I believe you wrote the fix to this :) but the current snapshot of swagger-core supports the responseClass="List[com.bar.Foo]", and is available in sonatype snapshots as 1.2.1-SNAPSHOT.
> I'm not sure of the best way to write unit tests for swagger though, if > there's interest in having this in the main version then happy to write > same if some guidance can be given. Seems as if the only code that tests > this is in the swagger-jaxrs module, though perhaps some should be in > swagger-core given that that's where the trait resides?
> Cheers
> -Mike > On Wednesday, 4 July 2012 17:16:20 UTC-4, tony tam wrote:
>> Returning the class would probably be better for the responseClass, good >> point. I'll see if that can be supported.
>> If you're not getting models for List[com.bar.Foo] you probably found a >> defect. I'll take a look at this.
>> I think that picking the return type out of the method is pretty tricky >> and that's why we made it explicit.
>> Tony
>> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>>> Regarding the responseClass parameter of @ApiOperation, is there a >>> reason why the parameter is the fully qualified name of the class rather >>> than Class<T>? >>> Using the fully qualified name is a bit dangerous as it can fail on code >>> refactoring and obviously is more error prone when it comes to typing (and >>> it's a runtime error).
>>> On another note, according to Tony, in order to set the return type to a >>> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >>> When I've tried that, I didn't get any model information for the API >>> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>>> I imagine the second question might be the answer to the first. However, >>> using some reflection magic, I'm fairly certain it can still be resolved by >>> using a class rather than a string.
>>> Also, I'd expect the @GET operations to use the return type of the >>> method by default. If developers want to override it with the responseClass >>> parameter, all the better, but since Response is not always used, the >>> forced usage of the responseClass parameter can be somewhat redundant (a >>> bit like having to say which HTTP method is used for the API call).
On Thursday, July 5, 2012 12:16:20 AM UTC+3, tony tam wrote:
> Returning the class would probably be better for the responseClass, good > point. I'll see if that can be supported.
> If you're not getting models for List[com.bar.Foo] you probably found a > defect. I'll take a look at this.
> I think that picking the return type out of the method is pretty tricky > and that's why we made it explicit.
> Tony
> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>> Regarding the responseClass parameter of @ApiOperation, is there a reason >> why the parameter is the fully qualified name of the class rather than >> Class<T>? >> Using the fully qualified name is a bit dangerous as it can fail on code >> refactoring and obviously is more error prone when it comes to typing (and >> it's a runtime error).
>> On another note, according to Tony, in order to set the return type to a >> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >> When I've tried that, I didn't get any model information for the API >> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>> I imagine the second question might be the answer to the first. However, >> using some reflection magic, I'm fairly certain it can still be resolved by >> using a class rather than a string.
>> Also, I'd expect the @GET operations to use the return type of the method >> by default. If developers want to override it with the responseClass >> parameter, all the better, but since Response is not always used, the >> forced usage of the responseClass parameter can be somewhat redundant (a >> bit like having to say which HTTP method is used for the API call).
Yes and no--the syntax is much better now, you can use this syntax:
responseClass="List[Customer]"
But it's still a string value, and brittle when refactoring. This is something that is very hard to get around in Java, period. Now if you venture past Java to scala, you'll see something with much better integration:
get("/:petId", operation( apiOperation[Pet] ("getPetById") .summary("Find pet by ID") .notes("Returns a pet based on ID")
Note the response class of [Pet] is typed in the api. This is an advantage of the reflection in scala 2.10, which I'll remind folks is compatible with java at the bytecode level.
On Thursday, February 7, 2013 1:06:52 AM UTC-8, Eyal Allweil wrote:
> Has their been any improvements where this is concerned? Is using the > short class name going to be supported in a future version of Swagger?
> On Thursday, July 5, 2012 12:16:20 AM UTC+3, tony tam wrote:
>> Returning the class would probably be better for the responseClass, good >> point. I'll see if that can be supported.
>> If you're not getting models for List[com.bar.Foo] you probably found a >> defect. I'll take a look at this.
>> I think that picking the return type out of the method is pretty tricky >> and that's why we made it explicit.
>> Tony
>> On Tuesday, July 3, 2012 1:29:58 PM UTC-7, Ron R wrote:
>>> Regarding the responseClass parameter of @ApiOperation, is there a >>> reason why the parameter is the fully qualified name of the class rather >>> than Class<T>? >>> Using the fully qualified name is a bit dangerous as it can fail on code >>> refactoring and obviously is more error prone when it comes to typing (and >>> it's a runtime error).
>>> On another note, according to Tony, in order to set the return type to a >>> List<Foo>, the responseClass parameter should be "List[com.bar.Foo]". >>> When I've tried that, I didn't get any model information for the API >>> listing (using com.bar.Foo worked fine). Any suggestions as to why?
>>> I imagine the second question might be the answer to the first. However, >>> using some reflection magic, I'm fairly certain it can still be resolved by >>> using a class rather than a string.
>>> Also, I'd expect the @GET operations to use the return type of the >>> method by default. If developers want to override it with the responseClass >>> parameter, all the better, but since Response is not always used, the >>> forced usage of the responseClass parameter can be somewhat redundant (a >>> bit like having to say which HTTP method is used for the API call).
