Add parameter-level description with new @Description annotation

endpoints-framework/src/main/java/com/google/api/server/spi/TypeLoader.java

@@ -174,6 +174,8 @@ private static Map<String, Class<? extends Annotation>> createAnnotationTypes(
         loadAnnotation(classLoader, "com.google.api.server.spi.config.ApiTransformer"));
     annotationTypes.put("DefaultValue",
         loadAnnotation(classLoader, "com.google.api.server.spi.config.DefaultValue"));
+    annotationTypes.put("Description",
+        loadAnnotation(classLoader, "com.google.api.server.spi.config.Description"));
     annotationTypes.put("Named",
         loadAnnotation(classLoader, "com.google.api.server.spi.config.Named"));
     annotationTypes.put("Nullable",

endpoints-framework/src/main/java/com/google/api/server/spi/config/Description.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.api.server.spi.config;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to specify the description of an API parameter.
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Description {
+  /**
+   * The parameter description.
+   */
+  String value() default "";
+}

endpoints-framework/src/main/java/com/google/api/server/spi/config/annotationreader/ApiConfigAnnotationReader.java

@@ -372,30 +372,37 @@ private void readMethodRequestParameters(EndpointMethod endpointMethod,
     for (int i = 0; i < parameterAnnotations.length; i++) {
       Annotation parameterName =
           AnnotationUtil.getNamedParameter(method, i, annotationTypes.get("Named"));
+      Annotation description =
+          AnnotationUtil.getParameterAnnotation(method, i, annotationTypes.get("Description"));
       Annotation nullable =
           AnnotationUtil.getNullableParameter(method, i, annotationTypes.get("Nullable"));
       Annotation defaultValue =
           AnnotationUtil.getParameterAnnotation(method, i, annotationTypes.get("DefaultValue"));
-      readMethodRequestParameter(methodConfig, parameterName, nullable, defaultValue,
+      readMethodRequestParameter(methodConfig, parameterName, description, nullable, defaultValue,
           parameterTypes[i]);
     }
   }
 
   private void readMethodRequestParameter(ApiMethodConfig methodConfig, Annotation parameterName,
-      Annotation nullable, Annotation defaultValue, Type type) throws IllegalArgumentException,
-          SecurityException, IllegalAccessException, InvocationTargetException,
-          NoSuchMethodException {
+      Annotation description, Annotation nullable, Annotation defaultValue, Type type) 
+      throws IllegalArgumentException, SecurityException, IllegalAccessException, 
+      InvocationTargetException, NoSuchMethodException {
     String parameterNameString = null;
     if (parameterName != null) {
       parameterNameString = getAnnotationProperty(parameterName, "value");
     }
+    String descriptionString = null;
+    if (description != null) {
+      descriptionString = getAnnotationProperty(description, "value");
+    }
     String defaultValueString = null;
     if (defaultValue != null) {
       defaultValueString = getAnnotationProperty(defaultValue, "value");
     }
 
     ApiParameterConfig parameterConfig =
-        methodConfig.addParameter(parameterNameString, nullable != null, defaultValueString, type);
+        methodConfig.addParameter(parameterNameString, descriptionString, nullable != null, 
+            defaultValueString, type);
 
     if (type instanceof Class) {
       Class<?> clazz = (Class<?>) type;

endpoints-framework/src/main/java/com/google/api/server/spi/config/jsonwriter/JsonConfigWriter.java

@@ -398,6 +398,7 @@ private void convertSimpleParameter(ApiParameterConfig config, ObjectNode parame
     }
 
     parameterNode.put("type", typeLoader.getParameterTypes().get(type));
+    parameterNode.put("description", config.getDescription());
     parameterNode.put("required", !config.getNullable() && config.getDefaultValue() == null);
 
     // TODO: Try to find a way to move default value interpretation/conversion into the

endpoints-framework/src/main/java/com/google/api/server/spi/config/model/ApiMethodConfig.java

@@ -292,10 +292,10 @@ public String getFullJavaName() {
    * Adds the given parameter to the configuration and updates the path to add the new parameter if
    * it is non-optional and has no default.
    */
-  public ApiParameterConfig addParameter(String name, boolean nullable, String defaultValue,
-      Type type) {
+  public ApiParameterConfig addParameter(String name, String description, boolean nullable, 
+      String defaultValue, Type type) {
     ApiParameterConfig config =
-        new ApiParameterConfig(this, name, nullable, defaultValue, type, typeLoader);
+        new ApiParameterConfig(this, name, description, nullable, defaultValue, type, typeLoader);
     parameterConfigs.add(config);
 
     if (config.getClassification() != Classification.INJECTED && name != null && !nullable

endpoints-framework/src/main/java/com/google/api/server/spi/config/model/ApiParameterConfig.java

@@ -31,6 +31,7 @@
 public class ApiParameterConfig {
   private final ApiMethodConfig apiMethodConfig;
   private final String name;
+  private final String description;
   private final boolean nullable;
   private final String defaultValue;
   private final Type type;
@@ -56,10 +57,11 @@ public enum Classification {
     UNKNOWN
   }
 
-  public ApiParameterConfig(ApiMethodConfig apiMethodConfig, String name, boolean nullable,
-      String defaultValue, Type type, TypeLoader typeLoader) {
+  public ApiParameterConfig(ApiMethodConfig apiMethodConfig, String name, String description, 
+      boolean nullable, String defaultValue, Type type, TypeLoader typeLoader) {
     this.apiMethodConfig = apiMethodConfig;
     this.name = name;
+    this.description = description;
     this.nullable = nullable;
     this.defaultValue = defaultValue;
     this.type = type;
@@ -71,6 +73,7 @@ public ApiParameterConfig(ApiMethodConfig apiMethodConfig, String name, boolean
   public ApiParameterConfig(ApiParameterConfig original, ApiMethodConfig apiMethodConfig) {
     this.apiMethodConfig = apiMethodConfig;
     this.name = original.name;
+    this.description = original.description;
     this.nullable = original.nullable;
     this.defaultValue = original.defaultValue;
     this.type = original.type;
@@ -111,6 +114,10 @@ public String getName() {
     return name;
   }
 
+  public String getDescription() {
+    return description;
+  }
+
   public boolean getNullable() {
     return nullable;
   }

endpoints-framework/src/main/java/com/google/api/server/spi/swagger/SwaggerGenerator.java

@@ -190,6 +190,7 @@ private void writeApiMethod(ApiMethodConfig methodConfig, EndpointMethod endpoin
           SerializableParameter parameter =
               isPathParameter ? new PathParameter() : new QueryParameter();
           parameter.setName(parameterConfig.getName());
+          parameter.setDescription(parameterConfig.getDescription());
           boolean required = isPathParameter || (!parameterConfig.getNullable()
               && parameterConfig.getDefaultValue() == null);
           if (parameterConfig.isRepeated()) {

endpoints-framework/src/test/java/com/google/api/server/spi/config/annotationreader/ApiConfigAnnotationReaderTest.java

@@ -39,6 +39,7 @@
 import com.google.api.server.spi.config.ApiTransformer;
 import com.google.api.server.spi.config.AuthLevel;
 import com.google.api.server.spi.config.DefaultValue;
+import com.google.api.server.spi.config.Description;
 import com.google.api.server.spi.config.Named;
 import com.google.api.server.spi.config.Nullable;
 import com.google.api.server.spi.config.Transformer;
@@ -746,6 +747,23 @@ final class Test extends DefaultValuedEndpoint<Long> {
     assertEquals(3141L, Long.parseLong(implValidTestDefaultValuedParameter(Test.class)));
   }
 
+  @Test
+  public void testParameterDescription() throws Exception {
+    @Api
+    final class TestParameterDescription {
+      public void foo(@Description("desc") String param) {}
+    }
+    ApiConfig config = createConfig(TestParameterDescription.class);
+    annotationReader.loadEndpointMethods(serviceContext, TestParameterDescription.class,
+        config.getApiClassConfig().getMethods());
+
+    ApiMethodConfig methodConfig =
+        Iterables.getOnlyElement(config.getApiClassConfig().getMethods().values());
+    ApiParameterConfig parameterConfig =
+        Iterables.getOnlyElement(methodConfig.getParameterConfigs());
+    assertEquals("desc", parameterConfig.getDescription());
+  }
+
   @ApiTransformer(TestSerializer.class)
   private static class TestBean {}
 

endpoints-framework/src/test/java/com/google/api/server/spi/config/annotationreader/ApiMethodAnnotationConfigTest.java

@@ -110,10 +110,11 @@ public void testDefaults() {
   public void testAddParameter() {
     assertEquals(0, config.getParameterConfigs().size());
 
-    config.addParameter("bleh", false, null, String.class);
+    config.addParameter("bleh", "desc", false, null, String.class);
 
     assertEquals(1, config.getParameterConfigs().size());
     assertEquals("bleh", config.getParameterConfigs().get(0).getName());
+    assertEquals("desc", config.getParameterConfigs().get(0).getDescription());
     assertEquals(String.class, config.getParameterConfigs().get(0).getType());
     assertTrue(config.getParameterConfigs().get(0).getSerializers().isEmpty());
     assertEquals(String.class, config.getParameterConfigs().get(0).getSchemaBaseType());
@@ -124,12 +125,12 @@ public void testAddParameter() {
   public void testAddParameter_nullableOrDefault() {
     assertEquals(0, config.getParameterConfigs().size());
 
-    config.addParameter("bleh", true, null, String.class);
+    config.addParameter("bleh", null, true, null, String.class);
     assertEquals(1, config.getParameterConfigs().size());
     assertEquals("bleh", config.getParameterConfigs().get(0).getName());
     assertEquals("overrideMethod1", config.getPath());
 
-    config.addParameter("foo", false, "42", String.class);
+    config.addParameter("foo", null, false, "42", String.class);
     assertEquals(2, config.getParameterConfigs().size());
     assertEquals("foo", config.getParameterConfigs().get(1).getName());
     assertEquals("overrideMethod1", config.getPath());

endpoints-framework/src/test/java/com/google/api/server/spi/config/model/ApiMethodConfigTest.java

@@ -106,7 +106,7 @@ public void testMethodNameNoResource() {
 
   @Test
   public void addInjectedParameter_notInPath() {
-    methodConfig.addParameter("alt", false, null, String.class);
+    methodConfig.addParameter("alt", null, false, null, String.class);
     assertThat(methodConfig.getPath()).doesNotContain("{alt}");
   }
 }

endpoints-framework/src/test/java/com/google/api/server/spi/config/model/ApiParameterConfigTest.java

@@ -85,9 +85,10 @@ public void setUp() throws Exception {
     Mockito.when(apiClassConfig.getApiConfig()).thenReturn(apiConfig);
     Mockito.when(apiConfig.getSerializationConfig()).thenReturn(serializationConfig);
 
-    config = new ApiParameterConfig(apiMethodConfig, "bleh", false, null, String.class, typeLoader);
-    configWithArray =
-        new ApiParameterConfig(apiMethodConfig, "bleh", false, null, Boolean[].class, typeLoader);
+    config = new ApiParameterConfig(apiMethodConfig, "bleh", null, false, null, String.class, 
+        typeLoader);
+    configWithArray = new ApiParameterConfig(apiMethodConfig, "bleh", null, false, null, 
+        Boolean[].class, typeLoader);
   }
 
   @Test
@@ -154,6 +155,7 @@ public void standardParametersAreInjected() {
   }
 
   private ApiParameterConfig createStandardParameter(String name) {
-    return new ApiParameterConfig(apiMethodConfig, "alt", false, null, String.class, typeLoader);
+    return new ApiParameterConfig(apiMethodConfig, "alt", null, false, null, String.class, 
+        typeLoader);
   }
 }

endpoints-framework/src/test/java/com/google/api/server/spi/config/validation/ApiConfigValidatorTest.java

@@ -202,7 +202,8 @@ final class TestSerializer extends DefaultValueSerializer<String, Boolean> {}
 
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, Integer.class).setSerializer(TestSerializer.class);
+        .addParameter("param", null, false, null, Integer.class)
+        .setSerializer(TestSerializer.class);
 
     try {
       validator.validate(config);
@@ -217,7 +218,7 @@ final class TestSerializer extends DefaultValueSerializer<String, Boolean> {}
 
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, Integer[].class)
+        .addParameter("param", null, false, null, Integer[].class)
         .setRepeatedItemSerializer(TestSerializer.class);
 
     try {
@@ -262,7 +263,7 @@ final class TestSerializer {}
 
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, Integer.class)
+        .addParameter("param", null, false, null, Integer.class)
         .setSerializer((Class<? extends Transformer<?, ?>>) (Class<?>) TestSerializer.class);
 
     try {
@@ -278,7 +279,7 @@ final class TestSerializer {}
 
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, Integer[].class)
+        .addParameter("param", null, false, null, Integer[].class)
         .setRepeatedItemSerializer(
             (Class<? extends Transformer<?, ?>>) (Class<?>) TestSerializer.class);
 
@@ -297,7 +298,7 @@ public void foo(List<String[]> l) {}
     }
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null,
+        .addParameter("param", null, false, null,
             Foo.class.getDeclaredMethod("foo", List.class).getGenericParameterTypes()[0]);
 
     try {
@@ -315,7 +316,7 @@ public void foo(List<String>[] l) {}
     }
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null,
+        .addParameter("param", null, false, null,
             Foo.class.getDeclaredMethod("foo", List[].class).getGenericParameterTypes()[0]);
 
     try {
@@ -333,7 +334,7 @@ public void foo(List<List<String>> l) {}
     }
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null,
+        .addParameter("param", null, false, null,
             Foo.class.getDeclaredMethod("foo", List.class).getGenericParameterTypes()[0]);
 
     try {
@@ -347,7 +348,7 @@ public void foo(List<List<String>> l) {}
   public void testArrayOfArraysParameter() throws Exception {
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, Integer[][].class);
+        .addParameter("param", null, false, null, Integer[][].class);
 
     try {
       validator.validate(config);
@@ -367,7 +368,7 @@ public void foo(T t) {}
 
     config.getApiClassConfig().getMethods()
         .get(methodToEndpointMethod(TestEndpoint.class.getMethod("getResultNoParams")))
-        .addParameter("param", false, null, unknownType);
+        .addParameter("param", null, false, null, unknownType);
 
     try {
       validator.validate(config);

endpoints-framework/src/test/java/com/google/api/server/spi/swagger/SwaggerGeneratorTest.java

@@ -28,6 +28,7 @@
 import com.google.api.server.spi.config.ApiIssuerAudience;
 import com.google.api.server.spi.config.ApiMethod;
 import com.google.api.server.spi.config.ApiMethod.HttpMethod;
+import com.google.api.server.spi.config.Description;
 import com.google.api.server.spi.config.Named;
 import com.google.api.server.spi.config.annotationreader.ApiConfigAnnotationReader;
 import com.google.api.server.spi.config.model.ApiConfig;
@@ -161,22 +162,22 @@ private void compareSwagger(Swagger expected, Swagger actual) throws Exception {
   private static class FooEndpoint {
     @ApiMethod(name = "foo.create", description = "create desc", path = "foos/{id}", 
         httpMethod = HttpMethod.PUT)
-    public Foo createFoo(@Named("id") String id, Foo foo) {
+    public Foo createFoo(@Named("id") @Description("id desc") String id, Foo foo) {
       return null;
     }
     @ApiMethod(name = "foo.get", description = "get desc", path = "foos/{id}", 
         httpMethod = HttpMethod.GET)
-    public Foo getFoo(@Named("id") String id) {
+    public Foo getFoo(@Named("id") @Description("id desc") String id) {
       return null;
     }
     @ApiMethod(name = "foo.update", description = "update desc", path = "foos/{id}", 
         httpMethod = HttpMethod.POST)
-    public Foo updateFoo(@Named("id") String id, Foo foo) {
+    public Foo updateFoo(@Named("id") @Description("id desc") String id, Foo foo) {
       return null;
     }
     @ApiMethod(name = "foo.delete", description = "delete desc", path = "foos/{id}", 
         httpMethod = HttpMethod.DELETE)
-    public Foo deleteFoo(@Named("id") String id) {
+    public Foo deleteFoo(@Named("id") @Description("id desc") String id) {
       return null;
     }
   }

endpoints-framework/src/test/resources/com/google/api/server/spi/swagger/foo_endpoint.swagger

@@ -22,6 +22,7 @@
           {
             "name": "id",
             "in": "path",
+            "description": "id desc",
             "required": true,
             "type": "string"
           }
@@ -47,6 +48,7 @@
           {
             "name": "id",
             "in": "path",
+            "description": "id desc",
             "required": true,
             "type": "string"
           }
@@ -72,6 +74,7 @@
           {
             "name": "id",
             "in": "path",
+            "description": "id desc",
             "required": true,
             "type": "string"
           }
@@ -97,6 +100,7 @@
           {
             "name": "id",
             "in": "path",
+            "description": "id desc",
             "required": true,
             "type": "string"
           }