Swagger scans methods on JAX-RS resources not annotated to be REST service methods

[oweise]

Information copied from this google group thread.

On scanning JAX-RS resources for the REST interface Swagger not only scans those methods that are annotated to be service methods with @GET/PUT/POST/DELETE and @Path. It seems to scan all methods on the resource class. This leads to a scanning failure if those non-service methods return types that are not appropriate to be served via service.

Imagine the following resource class, which is a draft of a real class on a Web Service we use:

@Path("/v1")
@Api(value="root")
@XmlRootElement(name=RootResource.RESOURCE_TYPE)
@XmlDiscriminatorValue(RootResource.RESOURCE_TYPE)
public class RootResource  {


  @Path(REFLIST_DBS + "/{dbkey}")
  @ApiOperation(value="Retrieve a database resource")
  public DatabaseResource getDatabase(@ApiParam(name="dbkey",value="Database key") @PathParam("dbkey") String dbKey) throws WGException {
      return new DatabaseResource(this, dbKey);
  }


  public RestApplication getApplication() {
     return _application;
  }
}

The method getDatabase() annotated with @Path is a service method, therefor should be scanned by Swagger. The method getApplication() is not annotated and is for internal use. Via scanning this method Swagger descends onto further types and their methods not meant to be service resources until, in our case, it reaches a type org.apache.log4j.spi.LoggerRepository which provokes a scanning error:

java.lang.IllegalArgumentException: Conflicting setter definitions for property "threshold": org.apache.log4j.spi.LoggerRepository#setThreshold(1 params) vs org.apache.log4j.spi.LoggerRepository#setThreshold(1 params)
at com.fasterxml.jackson.databind.introspect.POJOPropertyBuilder.getSetter(POJOPropertyBuilder.java:293)
at io.swagger.jackson.ModelResolver.resolve(ModelResolver.java:264)
at io.swagger.jackson.ModelResolver.resolve(ModelResolver.java:151)
...
at io.swagger.jaxrs.Reader.read(Reader.java:146)
at io.swagger.jaxrs.config.BeanConfig.setScan(BeanConfig.java:170)
at de.innovationgate.wga.services.rest.RestApplication.<init>(RestApplication.java:267)

While it might be untypical for JAX-RS resources to have non-service methods for any reason we would expect Swagger to ignore methods on resources that are not annotated to be service methods.

Involved maven libraries and their versions:

• swagger-jersey2-jaxrs (io.swagger) version 1.5.2
• jersey-server, jersey-media-moxy, jersey-media-json-processing (org.glassfish.jersey.core) version 2.19

[fehguy]

OK I've reproduced this with a simple test:

package io.swagger.resources;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.xml.bind.annotation.XmlRootElement;

@Path("/v1")
@Api(value="root")
@XmlRootElement
public class Resource1343 {
  RestApplication _application = null;

  @GET
  @Path("/{dbkey}")
  @ApiOperation(value="Retrieve a database resource")
  public DatabaseResource getDatabase(@ApiParam(name="dbkey",value="Database key") @PathParam("dbkey") String dbKey) throws Exception {
      return new DatabaseResource(this, dbKey);
  }

  // should not output anything in swagger
  public String doNothing() {
    return "nothing";
  }

  public RestApplication getApplication() {
     return _application;
  }

  static class RestApplication {
    public Integer id;
    public String name;
  }

  static class DatabaseResource {
    public String databaseName;

    public DatabaseResource(Object parent, String key) {

    }
  }
}

This adds the RestApplication in the definitions section of the JSON. Will work on a fix

[tomtit]

This issue #1252 looks similar.