Response Class

[Ron R]

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).

[tony tam]

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

[Ron R]

Why do you say that picking the return type out of the method can be tricky? Perhaps I can suggest a solution.

[tony tam]

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

[Ayush Gupta]

This is true of play framework too, where controller methods are expected to return an Action.

[Ron R]

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.

Just one of the limitations of JAX-RS.

[Michael Dekmetzian]

Just for the sake of anyone reading this today, List[com.bar.Foo] is indeed not correct. 

You should use:

@ApiOperation( value="xxx" notes="yyy" responseClass="com.bar.Foo", multiValueResponse=true)

Internally the representation will be wrapped as List[Foo] after the fact but based on my reading you cannot declare it as such. 

Writing the code to allow for responseClass="List[com.bar.Foo]" isn't super complex, two methods as per this pastebin would do it: 

http://pastebin.com/wY1zjwys

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

[tony tam]

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.

Tony

[Eyal Allweil]

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:

[tony tam]

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:

https://github.com/wordnik/swagger-core/blob/master/samples/scala-scalatra/src/main/scala/com/wordnik/swagger/sample/api/PetstoreApi.scala#L34

Or copied from there:

  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.

Tony