Documenting the response model in Swagger

[Lokuma]

I am trying to document the response model using  @ApiOperation(value = "",notes = "",  response = XXX.class) following the example in petstore. Some of the response classes are ignored and not displayed, some of them are displayed. I specify the same response class in multiple resources and it got picked up only once by one resource. I tried adding httpMethod property in case the method is not picked up, but it did not help.

I am trying to understand what the issue could be, and how to troubleshoot it.

Thank you.

Here is a code example:

//The response class is not displayed at all for this resource

 @GET

  @Path("/{groupId}")

  @Produces(MediaType.APPLICATION_JSON)

  @ApiOperation( value = "",notes = "",  response = UserGroupResults.class)

  public Response getUserGroup( 

  .......

//******************************

//But it gets displayed properly by this one

   @POST

  @Produces({MediaType.APPLICATION_JSON})

  @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_FORM_URLENCODED})

  @ApiOperation( value = "",notes = "",  response = UserGroupResults.class)

  public Response createUserGroup(

  ......

  // and the response looks like this. The only not correct thing here is (Status 200). POST returns 201:

  

 Response Class (Status 200)

Model

UserGroup {

id (string, optional),

name (string, optional),

description (string, optional),

email (string, optional)

}

 //************************* 

@ApiModel( value = "UserGroup" )

@XmlRootElement(name = "UserGroupResults")

public class UserGroupResults {

  private String id;

  private String name;

  private String email;

  private String description;

  /**

   * 

   * @param name

   */

   public void setName(String name) {

    this.name = ( name == null ? "" : name );

  }

  /**

   * 

   * @return name

   */

  @XmlElement(name = "name")

  public String getName() {

    return this.name;

  }

  /**

   * 

   * @param email

   */

  public void setEmail(String email) { 

    this.email = ( email == null ? "" : email );

  }

  /**

   * 

   * @return email

   */

  @XmlElement(name = "email")

  public String getEmail() {

    return this.email;

  }

  /**

   * 

   * @param description

   */

  public void setDescription(String description) {

    this.description = ( description == null ? "" : description );

  }

  /**

   * 

   * @return description

   */

  @XmlElement(name = "description")

  public String getDescription() {

    return this.description;

  }

  /**

   * Getter for UserGroup's id.

   * @return

   */

  @XmlElement(name = "id")

  public String getId() {

    return id;

  }

  /**

   * Setter for UserGroup's id.

   * @param id

   */

  public void setId(String id) {

    this.id = id;

  }

}

/****************************************

We are using jersey 2.1 and javax-rs to build our REST API in JAVA. We use swagger 2.0 to document it.

These are the libraries from swagger we use to compile, just in case if they create the problem:

swagger-annotations-1.5.0.jar

swagger-jersey2-jaxrs-1.5.0.jar

swagger-core-1.5.0.jar

reflections-0.9.9.jar

guava-15.0.jar

json4s-core_2.10-3.2.11.jar

json4s-ast_2.10-3.2.11.jar

json4s-ext_2.10-3.2.11.jar

json4s-native_2.10-3.2.11.jar

json4s-jackson_2.10-3.2.11.jar

jackson-core-2.4.2.jar

jackson-databind-2.4.2.jar

jackson-annotations-2.4.2.jar

swagger-models-1.5.0.jar

slf4j-api-1.6.3.jar

commons-lang3-3.2.1.jar

[Ron Ratovsky]

What you describe is an odd behavior and should definitely not be.

As an initial troubleshooting step, I'd ask that you'd upgrade to swagger-core 1.5.3 and see if that resolves the issue.

Can you do that and report back please?

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Lokuma]

Using swagger-core-1.5.3.jar makes my application to fail when scanning the resources at  beanConfig.setScan(true);

I tried adding and removing some of the new dependent jars, such as jackson-core-2.4.5.jar, jackson-databind-2.4.5.jar, jackson-annotations-2.4.5.jar, and swagger-models-1.5.3.jar,  but no luck so far.

 Is there anything else I am missing?

Thanks for helping with this, Ron!

swagger-annotations-1.5.0.jar

swagger-jersey2-jaxrs-1.5.0.jar

swagger-core-1.5.3.jar

reflections-0.9.9.jar

guava-15.0.jar

json4s-core_2.10-3.2.11.jar

json4s-ast_2.10-3.2.11.jar

json4s-ext_2.10-3.2.11.jar

json4s-native_2.10-3.2.11.jar

json4s-jackson_2.10-3.2.11.jar

jackson-core-2.4.5.jar

jackson-databind-2.4.5.jar

jackson-annotations-2.4.5.jar

swagger-models-1.5.3.jar

slf4j-api-1.6.3.jar

commons-lang3-3.2.1.jar

[Ron Ratovsky]

You need to upgrade all the libraries within the swagger-core project to 1.5.3, including swagger-annotations and swagger-jersey2-jaxrs, so check after updating those.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lokuma]

Hi Ron,

I upgraded all the jars to version 1.5.3. My code compiles fine, but still I cannot get pass the setScan() function. After some debugging I see the execution gets stuck at line 99 (in red below) in io.swagger.jaxrs.utils.ReaderUtils.class:

   private static List<Parameter> collectParameters(Type type, List<Annotation> annotations) {

        final Iterator<SwaggerExtension> chain = SwaggerExtensions.chain();

        return chain.hasNext() ? chain.next().extractParameters(annotations, type, new HashSet<Type>(), chain) :

                Collections.<Parameter>emptyList();

    }

Any idea what might be going on?

This is the current set of libraries I am using.It might contain more than I need. I tried different sets, by excluding and including some, but the result is the same

swagger-annotations-1.5.3.jar

swagger-jaxrs-1.5.3.jar

swagger-jersey2-jaxrs-1.5.3.jar

swagger-jersey-jaxrs-1.5.3.jar

swagger-core-1.5.3.jar

swagger-models-1.5.3.jar

reflections-0.9.9.jar

guava-15.0.jar

json4s-core_2.10-3.2.11.jar

json4s-ast_2.10-3.2.11.jar

json4s-ext_2.10-3.2.11.jar

json4s-native_2.10-3.2.11.jar

json4s-jackson_2.10-3.2.11.jar

jackson-core-2.4.5.jar

jackson-databind-2.4.5.jar

jackson-annotations-2.4.5.jar

jackson-jaxrs-json-provider-2.4.5.jar

jackson-dataformat-yaml-2.4.5.jar

slf4j-api-1.6.3.jar

commons-lang3-3.2.1.jar

Thanks.

On Thursday, October 1, 2015 at 1:07:59 PM UTC-7, Lokuma wrote:

[Ron Ratovsky]

I assume you're not using maven or another dependency management system? It's fairly difficult to keep a proper list of dependencies otherwise.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lokuma]

I was able to figure out the correct dependencies for 1.5.3 and got the swagger functioning again. Unfortunately, the response models still behave the same way, as described in the initial post.

On Thursday, October 1, 2015 at 1:07:59 PM UTC-7, Lokuma wrote:

[Ron Ratovsky]

Sorry to hear that. Do you see the model defined properly in the JSON itself? Can you share the JSON?

--

You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lokuma]

With Ron's help the response models appeared properly. Thank you very much, Ron!

For the benefit of everybody encountering a similar issue, the response class can be defined in @ApiOperation, and @ApiResponse annotations. The definition in @ApiResponse with code 200, takes precedence over  the one in  @ApiOperation.

 @GET

  @Path("/{groupId}")

  @Produces(MediaType.APPLICATION_JSON)

  @ApiOperation( value = "",notes = "")

 @ApiResponses(value = { @ApiResponse(code = 200, message = "", response = UserGroupResults.class, responseContainer = "List"),

  @ApiResponse(code = 400, message = "")

  })

  public Response getUserGroup( 

.....

On Thursday, October 1, 2015 at 1:07:59 PM UTC-7, Lokuma wrote:

[Ron Ratovsky]

Glad it worked out, and thanks for sharing the solution with everyone.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.