Add description on enum constants (#133)

* Fix enum constant name to be backward compatible with endpoints v1

* Add description on enum constant by using the @description annotation

* Iterate on enum fields instead of constants to avoid reflection exception

* Update Javadoc on @description annotation

* Add description on $ref reference

* Fix indent and update copyright

Author: Clément Denis

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

@@ -21,9 +21,10 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation to specify the description of an API parameter.
+ * Annotation to specify the description of an API parameter or enum constants.
+ * The description will be ignored if the annotation is used on resource fields.
  */
-@Target(ElementType.PARAMETER)
+@Target({ElementType.PARAMETER, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Description {
   /**

Diff for: endpoints-framework/src/main/java/com/google/api/server/spi/config/model/SchemaRepository.java

@@ -2,6 +2,7 @@
 
 import com.google.api.client.util.Maps;
 import com.google.api.server.spi.TypeLoader;
+import com.google.api.server.spi.config.Description;
 import com.google.api.server.spi.config.ResourcePropertySchema;
 import com.google.api.server.spi.config.ResourceSchema;
 import com.google.api.server.spi.config.annotationreader.ApiAnnotationIntrospector;
@@ -153,9 +154,12 @@ private Schema getOrCreateTypeForConfig(
       Schema.Builder builder = Schema.builder()
           .setName(Types.getSimpleName(type, config.getSerializationConfig()))
           .setType("string");
-      for (Object enumConstant : type.getRawType().getEnumConstants()) {
-        builder.addEnumValue(enumConstant.toString());
-        builder.addEnumDescription("");
+      for (java.lang.reflect.Field field : type.getRawType().getFields()) {
+        if (field.isEnumConstant()) {
+          builder.addEnumValue(field.getName());
+          Description description = field.getAnnotation(Description.class);
+          builder.addEnumDescription(description == null ? "" : description.value());
+        }
       }
       schema = builder.build();
       typesForConfig.put(type, schema);

Diff for: endpoints-framework/src/main/java/com/google/api/server/spi/discovery/DiscoveryGenerator.java

@@ -238,7 +238,9 @@ private JsonSchema convertToDiscoverySchema(Schema schema) {
 
   private JsonSchema convertToDiscoverySchema(Field f) {
     if (f.schemaReference() != null) {
-      return new JsonSchema().set$ref(f.schemaReference().get().name());
+      return new JsonSchema()
+          .setDescription(f.description())
+          .set$ref(f.schemaReference().get().name());
     }
     JsonSchema fieldSchema = new JsonSchema()
         .setType(f.type().getDiscoveryType())

Diff for: endpoints-framework/src/test/java/com/google/api/server/spi/config/jsonwriter/ResourceSchemaProviderTest.java

@@ -31,6 +31,7 @@
 import com.google.api.server.spi.config.model.ApiConfig;
 import com.google.api.server.spi.testing.DefaultValueSerializer;
 import com.google.api.server.spi.testing.TestEndpoint;
+import com.google.api.server.spi.testing.TestEnum;
 import com.google.common.reflect.TypeToken;
 
 import org.junit.Before;
@@ -77,6 +78,7 @@ public void testDescribedProperty() {
     ResourceSchema schema = getResourceSchema(DescribedPropertyBean.class);
     assertEquals("description of foo", schema.getProperties().get("foo").getDescription());
     assertEquals("description of bar", schema.getProperties().get("bar").getDescription());
+    assertEquals("description of choice", schema.getProperties().get("choice").getDescription());
   }
 
   @Test
@@ -197,6 +199,8 @@ private static class DescribedPropertyBean {
     public String getBar() {
       return null;
     }
+    @ApiResourceProperty(description = "description of choice")
+    public TestEnum choice;
   }
 
   /**

Diff for: endpoints-framework/src/test/resources/com/google/api/server/spi/discovery/foo_with_description_endpoint.json

@@ -14,8 +14,8 @@
   "description": "Just Foo Things",
   "discoveryVersion": "v1",
   "icons": {
-    "x16": "http://www.google.com/images/icons/product/search-16.gif",
-    "x32": "http://www.google.com/images/icons/product/search-32.gif"
+    "x16": "https://www.gstatic.com/images/branding/product/1x/googleg_16dp.png",
+    "x32": "https://www.gstatic.com/images/branding/product/1x/googleg_32dp.png"
   },
   "id": "foo:v1",
   "kind": "discovery#restDescription",
@@ -228,6 +228,10 @@
     "FooDescription": {
       "id": "FooDescription",
       "properties": {
+        "choice": {
+          "$ref": "TestEnumDescription",
+          "description": "description of choice"
+        },
         "name": {
           "description":"description of name",
           "type": "string"
@@ -239,6 +243,18 @@
         }
       },
       "type": "object"
+    },
+    "TestEnumDescription": {
+      "enum": [
+        "VALUE1",
+        "VALUE2"
+      ],
+      "enumDescriptions": [
+        "description of value1",
+        "description of value2"
+      ],
+      "id": "TestEnumDescription",
+      "type":"string"
     }
   },
   "servicePath": "foo/v1/",

Diff for: endpoints-framework/src/test/resources/com/google/api/server/spi/swagger/foo_with_description_endpoint.swagger

@@ -234,8 +234,18 @@
         }
       }
     },
+    "TestEnumDescription": {
+      "enum": [
+        "VALUE1",
+        "VALUE2"
+      ]
+    },
     "FooDescription": {
       "properties": {
+        "choice": {
+          "description": "description of choice",
+          "$ref": "#/definitions/TestEnumDescription"
+        },
         "name": {
           "description": "description of name",
           "type": "string"

Diff for: test-utils/src/main/java/com/google/api/server/spi/testing/FooDescription.java

@@ -26,6 +26,8 @@ public class FooDescription {
   private String name;
   private int value;
   private String hidden;
+  @ApiResourceProperty(description = "description of choice")
+  private TestEnumDescription choice;
 
   public String getName() {
     return name;
@@ -43,4 +45,8 @@ private String getHidden() {
   private void setHidden(String hidden) {
     this.hidden = hidden;
   }
+
+  public TestEnumDescription getChoice() {
+    return choice;
+  }
 }

Diff for: test-utils/src/main/java/com/google/api/server/spi/testing/TestEnumDescription.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2018 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.testing;
+
+import com.google.api.server.spi.config.Description;
+
+public enum TestEnumDescription {
+  @Description("description of value1")
+  VALUE1,
+  @Description("description of value2")
+  VALUE2;
+
+  public String notAConstant;
+}