Merge pull request #1136 from swagger-api/merging-issue-1085

Merge branch 'issue-1085'

Author: Ole Lensmar

modules/swagger-jaxrs/src/main/java/io/swagger/jaxrs/Reader.java

@@ -18,10 +18,12 @@
 
 import com.fasterxml.jackson.databind.JavaType;
 import com.fasterxml.jackson.databind.type.TypeFactory;
+import com.google.common.collect.Collections2;
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import io.swagger.annotations.ApiResponse;
 import io.swagger.annotations.ApiResponses;
 import io.swagger.annotations.Authorization;
@@ -68,11 +70,14 @@
 import javax.ws.rs.HttpMethod;
 import javax.ws.rs.Produces;
 import java.lang.annotation.Annotation;
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.EnumSet;
 import java.util.HashMap;
@@ -83,14 +88,36 @@
 import java.util.Map;
 import java.util.Set;
 
+import javax.ws.rs.Consumes;
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.HttpMethod;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+
+import org.apache.commons.lang3.StringUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 public class Reader {
   private static final Logger LOGGER = LoggerFactory.getLogger(Reader.class);
   private static final String SUCCESSFUL_OPERATION = "successful operation";
   private static final String PATH_DELIMITER = "/";
 
+  private static final Set<Class<? extends Annotation>> FIELD_ANNOTATIONS;
   private final ReaderConfig config;
   private Swagger swagger;
 
+  static {
+    final Set<Class<? extends Annotation>> fieldAnnotations = new HashSet<Class<? extends Annotation>>();
+    fieldAnnotations.add(PathParam.class);
+    fieldAnnotations.add(QueryParam.class);
+    fieldAnnotations.add(HeaderParam.class);
+    fieldAnnotations.add(ApiParam.class);
+    fieldAnnotations.add(ApiImplicitParam.class);
+    FIELD_ANNOTATIONS = Collections.unmodifiableSet(fieldAnnotations);
+  }
+
   public Reader(Swagger swagger) {
     this(swagger, null);
   }
@@ -270,8 +297,8 @@ protected Swagger read(Class<?> cls, String parentPath, String parentMethod, boo
           final ApiOperation apiOperation = getAnnotation(method, ApiOperation.class);
           String httpMethod = extractOperationMethod(apiOperation, method, SwaggerExtensions.chain());
 
-          Operation operation = parseMethod(method);
-          if(operation == null)
+          Operation operation = parseMethod(method, collectGlobalParameters(cls));
+          if(operation == null) 
             continue;
           if(parentParameters != null) {
             for(Parameter param : parentParameters) {
@@ -668,6 +695,10 @@ public Map<String, Property> parseResponseHeaders(ResponseHeader[] headers) {
   }
 
   public Operation parseMethod(Method method) {
+    return parseMethod(method, Collections.<Parameter> emptyList());
+  }
+
+  private Operation parseMethod(Method method, List<Parameter> globalParameters) {
     Operation operation = new Operation();
 
     ApiOperation apiOperation = getAnnotation(method, ApiOperation.class);
@@ -851,6 +882,10 @@ else if(responseType != null && !isVoid(responseType)) {
       hidden = apiOperation.hidden();
 
     // process parameters
+    for (Parameter globalParameter : globalParameters) {
+      operation.parameter(globalParameter);
+    }
+
     Type[] genericParameterTypes = method.getGenericParameterTypes();
     Annotation[][] paramAnnotations = method.getParameterAnnotations();
     for(int i = 0; i < genericParameterTypes.length; i++) {
@@ -1005,6 +1040,31 @@ private static boolean isResourceClass(Class<?> cls) {
     return cls.getAnnotation(Api.class) != null;
   }
 
+  private List<Parameter> collectGlobalParameters(Class<?> cls) {
+    final List<Parameter> globalParameters = new ArrayList<Parameter>();
+
+    // look for constructor-level annotated properties
+    final Constructor<?> constructor = ReflectionUtils.findConstructor(cls);
+    if (constructor != null) {
+      final Type[] genericParameterTypes = constructor.getGenericParameterTypes();
+      final Annotation[][] annotations = constructor.getParameterAnnotations();
+      for (int i = 0; i < genericParameterTypes.length; i++) {
+        globalParameters.addAll(getParameters(genericParameterTypes[i], Arrays.asList(annotations[i])));
+      }
+    }
+
+    // look for field-level annotated properties
+    for (Field field : cls.getDeclaredFields()) {
+      final List<Annotation> annotations = Arrays.asList(field.getAnnotations());
+      final Collection<Class<? extends Annotation>> types = Collections2.transform(annotations, ReflectionUtils.createAnnotationTypeGetter());
+      if (!Collections.disjoint(types, FIELD_ANNOTATIONS)) {
+        globalParameters.addAll(getParameters(field.getGenericType(), annotations));
+      }
+    }
+
+    return globalParameters;
+  }
+
   enum ContainerWrapper {
     LIST("list") {
       @Override

modules/swagger-jaxrs/src/main/java/io/swagger/jaxrs/utils/ReflectionUtils.java

@@ -1,11 +1,35 @@
 package io.swagger.jaxrs.utils;
 
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
 import java.lang.reflect.Type;
 import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.QueryParam;
+
+import com.google.common.base.Function;
+import com.google.common.collect.Collections2;
 
 public class ReflectionUtils {
 
+  private static final Set<Class<? extends Annotation>> CONSTRUCTOR_ANNOTATIONS;
+
+  static {
+    final Set<Class<? extends Annotation>> constructorAnnotations = new HashSet<Class<? extends Annotation>>();
+    constructorAnnotations.add(PathParam.class);
+    constructorAnnotations.add(QueryParam.class);
+    constructorAnnotations.add(HeaderParam.class);
+    CONSTRUCTOR_ANNOTATIONS = Collections.unmodifiableSet(constructorAnnotations);
+  }
+
   /**
    * Checks if the method methodToFind is the overridden method from the superclass.
    *
@@ -83,4 +107,80 @@ public static Method findMethod(Method methodToFind, Class<?> cls) {
     }
     return null;
   }
+
+  /**
+   * Searches for constructor suitable for resource instantiation.
+   * <p/>
+   * If more constructors exists the one with the most injectable parameters will be selected.
+   *
+   * @param cls is the class where to search
+   * @return the suitable constructor
+   */
+  public static Constructor<?> findConstructor(Class<?> cls) {
+    if (cls.isLocalClass() || (cls.isMemberClass() && !Modifier.isStatic(cls.getModifiers()))) {
+      return null;
+    }
+
+    Constructor<?> selected = null;
+    int selectedCount = 0;
+    int maxParams = -1;
+    for (Constructor<?> constructor : cls.getDeclaredConstructors()) {
+      final Class<?>[] parameterTypes = constructor.getParameterTypes();
+      if (parameterTypes.length >= maxParams && isCompatible(constructor)) {
+        if (parameterTypes.length > maxParams) {
+          maxParams = parameterTypes.length;
+          selectedCount = 0;
+        }
+
+        selected = constructor;
+        selectedCount++;
+      }
+    }
+
+    return selectedCount == 1 ? selected : null;
+  }
+
+  /**
+   * Returns an implementation of {@link Function} for getting annotation types.
+   * @return the implementation of {@link Function} for getting annotation types
+   */
+  public static Function<Annotation, Class<? extends Annotation>> createAnnotationTypeGetter() {
+    return new Function<Annotation, Class<? extends Annotation>>() {
+      @Override
+      public Class<? extends Annotation> apply(Annotation annotation) {
+        return annotation.annotationType();
+      }
+    };
+  }
+
+  /**
+   * Checks if the passed constructor is suitable for resource instantiation.
+   * Repeats the logic of the {@link org.glassfish.jersey.internal.inject.JerseyClassAnalyzer#isCompatible(java.lang.reflect.Constructor)}
+   * @param constructor the constructor to be checked
+   * @return true if the constructor is suitable or false otherwise
+   */
+  private static boolean isCompatible(Constructor<?> constructor) {
+    for (Annotation annotation : constructor.getAnnotations()) {
+      // use string name to avoid additional dependencies
+      if ("javax.inject.Inject".equals(annotation.annotationType().getName())) {
+        return true;
+      }
+    }
+
+    if (!Modifier.isPublic(constructor.getModifiers())) {
+      final int access = Modifier.PUBLIC | Modifier.PROTECTED | Modifier.PRIVATE;
+      return constructor.getParameterTypes().length == 0 &&
+        (constructor.getDeclaringClass().getModifiers() & access) == constructor.getModifiers();
+    }
+
+    for (Annotation[] paramAnnotations : constructor.getParameterAnnotations()) {
+      final Collection<Class<? extends Annotation>> tmp = Collections2.transform(Arrays.asList(paramAnnotations),
+        ReflectionUtils.createAnnotationTypeGetter());
+      if (Collections.disjoint(tmp, CONSTRUCTOR_ANNOTATIONS)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
 }

modules/swagger-jaxrs/src/test/scala/ReaderTest.scala

@@ -81,6 +81,24 @@ class ReaderTest extends FlatSpec with Matchers {
     swagger.getPaths().get("/{id}/value").getPut.getProduces.get(0) should equal ("text/plain")
   }
 
+  it should "scan class level and field level annotations" in {
+    val swagger = new Reader(new Swagger()).read(classOf[ResourceWithKnownInjections])
+
+    val resourceParameters = swagger.getPaths().get("/resource/{id}").getGet().getParameters()
+    resourceParameters should not equal (null)
+    resourceParameters.size() should equal (3)
+    resourceParameters.get(0).asInstanceOf[PathParameter].getName() should equal ("id")
+    resourceParameters.get(1).asInstanceOf[QueryParameter].getName() should equal ("fieldParam")
+    resourceParameters.get(2).asInstanceOf[QueryParameter].getName() should equal ("methodParam")
+
+    val subResourceParameters = swagger.getPaths().get("/resource/{id}/subresource").getGet().getParameters()
+    subResourceParameters should not equal (null)
+    subResourceParameters.size() should equal (3)
+    subResourceParameters.get(0).asInstanceOf[PathParameter].getName() should equal ("id")
+    subResourceParameters.get(1).asInstanceOf[QueryParameter].getName() should equal ("fieldParam")
+    subResourceParameters.get(2).asInstanceOf[QueryParameter].getName() should equal ("subResourceParam")
+  }
+
   def isValidRestPath(method: Method) = {
     if(Set(Option(method.getAnnotation(classOf[GET])),
       Option(method.getAnnotation(classOf[PUT])),

modules/swagger-jaxrs/src/test/scala/resources/ResourceWithKnownInjections.java

@@ -0,0 +1,64 @@
+package resources;
+
+import io.swagger.annotations.Api;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.Request;
+
+@Path("/resource/{id}")
+@Api(value = "/resource", description = "Summary of injections resource")
+@Produces({"application/json", "application/xml"})
+public class ResourceWithKnownInjections {
+
+  private Integer constructorParam;
+  @QueryParam("fieldParam")
+  private String fieldParam; // injection into a class field
+
+  // injection into a constructor parameter
+  public ResourceWithKnownInjections(@PathParam("id") Integer constructorParam) {
+    this.constructorParam = constructorParam;
+  }
+
+  @GET
+  public String get(@QueryParam("methodParam") String methodParam) {
+    // injection into a resource method parameter
+    final StringBuilder sb = new StringBuilder();
+    sb.append("Constructor param: ").append(constructorParam).append("\n");
+    sb.append("Field param: ").append(fieldParam).append("\n");
+    sb.append("Method param: ").append(methodParam).append("\n");
+    return sb.toString();
+  }
+
+  @Path("/subresource")
+  public SubResource subResourceLocator(@QueryParam("subResourceParam") String subResourceParam) {
+    // injection into a sub resource locator parameter
+    return new SubResource(subResourceParam);
+  }
+
+  @Context
+  public void setRequest(Request request) {
+    // injection into a setter method
+  }
+
+  @Api(description = "Sub resource")
+  public static class SubResource {
+
+    private String subResourceParam;
+
+    public SubResource(String subResourceParam) {
+      this.subResourceParam = subResourceParam;
+    }
+
+    @GET
+    public String get() {
+      final StringBuilder sb = new StringBuilder();
+      sb.append("Sub Resource: ").append(subResourceParam);
+      return sb.toString();
+    }
+  }
+}