Add description in discovery file

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

@@ -228,6 +228,7 @@ private JsonSchema convertToDiscoverySchema(Schema schema) {
       }
       docSchema.setProperties(fields);
     }
+    docSchema.setDescription(schema.description());
     if (!schema.enumValues().isEmpty()) {
       docSchema.setEnum(new ArrayList<>(schema.enumValues()));
       docSchema.setEnumDescriptions(new ArrayList<>(schema.enumDescriptions()));
@@ -241,6 +242,7 @@ private JsonSchema convertToDiscoverySchema(Field f) {
     }
     JsonSchema fieldSchema = new JsonSchema()
         .setType(f.type().getDiscoveryType())
+        .setDescription(f.description())
         .setFormat(f.type().getDiscoveryFormat());
     if (f.type() == FieldType.ARRAY) {
       fieldSchema.setItems(convertToDiscoverySchema(f.arrayItemSchema()));

endpoints-framework/src/test/java/com/google/api/server/spi/discovery/DiscoveryGeneratorTest.java

@@ -32,6 +32,7 @@
 import com.google.api.server.spi.testing.ArrayEndpoint;
 import com.google.api.server.spi.testing.EnumEndpoint;
 import com.google.api.server.spi.testing.EnumEndpointV2;
+import com.google.api.server.spi.testing.FooDescriptionEndpoint;
 import com.google.api.server.spi.testing.FooEndpoint;
 import com.google.api.server.spi.testing.MultipleParameterEndpoint;
 import com.google.api.server.spi.testing.NamespaceEndpoint;
@@ -152,6 +153,13 @@ public void testWriteDiscovery_AbsoluteCommonPathEndpoint() throws Exception {
     compareDiscovery(expected, doc);
   }
 
+  @Test
+  public void testWriteDiscovery_FooEndpointWithDescription() throws Exception {
+    RestDescription doc = getDiscovery(context, FooDescriptionEndpoint.class);
+    RestDescription expected = readExpectedAsDiscovery("foo_with_description_endpoint.json");
+    compareDiscovery(expected, doc);
+  }
+
   @Test
   public void testWriteDiscovery_multipleApisWithSharedSchema() throws Exception {
     // Read in an API that uses a resource with fields that have their own schema, then read in

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

@@ -0,0 +1,247 @@
+{
+  "auth": {
+    "oauth2": {
+      "scopes": {
+        "https://www.googleapis.com/auth/userinfo.email": {
+          "description": "View your email address"
+        }
+      }
+    }
+  },
+  "basePath": "/api/foo/v1/",
+  "baseUrl": "https://discovery-test.appspot.com/api/foo/v1/",
+  "batchPath": "batch",
+  "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"
+  },
+  "id": "foo:v1",
+  "kind": "discovery#restDescription",
+  "methods": {
+    "toplevel": {
+      "httpMethod": "POST",
+      "id": "foo.toplevel",
+      "path": "foos",
+      "response": {
+        "$ref": "CollectionResponse_FooDescription"
+      },
+      "scopes": [
+        "https://www.googleapis.com/auth/userinfo.email"
+      ]
+    }
+  },
+  "name": "foo",
+  "parameters": {
+    "alt": {
+      "default": "json",
+      "description": "Data format for the response.",
+      "enum": [
+        "json"
+      ],
+      "enumDescriptions": [
+        "Responses with Content-Type of application/json"
+      ],
+      "location": "query",
+      "type": "string"
+    },
+    "fields": {
+      "description": "Selector specifying which fields to include in a partial response.",
+      "location": "query",
+      "type": "string"
+    },
+    "key": {
+      "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
+      "location": "query",
+      "type": "string"
+    },
+    "oauth_token": {
+      "description": "OAuth 2.0 token for the current user.",
+      "location": "query",
+      "type": "string"
+    },
+    "prettyPrint": {
+      "default": "true",
+      "description": "Returns response with indentations and line breaks.",
+      "location": "query",
+      "type": "boolean"
+    },
+    "quotaUser": {
+      "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters. Overrides userIp if both are provided.",
+      "location": "query",
+      "type": "string"
+    },
+    "userIp": {
+      "description": "IP address of the site where the request originates. Use this if you want to enforce per-user limits.",
+      "location": "query",
+      "type": "string"
+    }
+  },
+  "protocol": "rest",
+  "resources": {
+    "foo": {
+      "methods": {
+        "create": {
+          "description": "create desc",
+          "httpMethod": "PUT",
+          "id": "foo.foo.create",
+          "parameterOrder": [
+            "id"
+          ],
+          "parameters": {
+            "id": {
+              "description": "id desc",
+              "location": "path",
+              "required": true,
+              "type": "string"
+            }
+          },
+          "path": "foos/{id}",
+          "request": {
+            "$ref": "FooDescription",
+            "parameterName": "resource"
+          },
+          "response": {
+            "$ref": "FooDescription"
+          },
+          "scopes": [
+            "https://www.googleapis.com/auth/userinfo.email"
+          ]
+        },
+        "delete": {
+          "description": "delete desc",
+          "httpMethod": "DELETE",
+          "id": "foo.foo.delete",
+          "parameterOrder": [
+            "id"
+          ],
+          "parameters": {
+            "id": {
+              "description": "id desc",
+              "location": "path",
+              "required": true,
+              "type": "string"
+            }
+          },
+          "path": "foos/{id}",
+          "response": {
+            "$ref": "FooDescription"
+          },
+          "scopes": [
+            "https://www.googleapis.com/auth/userinfo.email"
+          ]
+        },
+        "get": {
+          "description": "get desc",
+          "httpMethod": "GET",
+          "id": "foo.foo.get",
+          "parameterOrder": [
+            "id"
+          ],
+          "parameters": {
+            "id": {
+              "description": "id desc",
+              "location": "path",
+              "required": true,
+              "type": "string"
+            }
+          },
+          "path": "foos/{id}",
+          "response": {
+            "$ref": "FooDescription"
+          },
+          "scopes": [
+            "https://www.googleapis.com/auth/userinfo.email"
+          ]
+        },
+        "list": {
+          "description": "list desc",
+          "httpMethod": "GET",
+          "id": "foo.foo.list",
+          "parameterOrder": [
+            "n"
+          ],
+          "parameters": {
+            "n": {
+              "format": "int32",
+              "location": "query",
+              "required": true,
+              "type": "integer"
+            }
+          },
+          "path": "foos",
+          "response": {
+            "$ref": "CollectionResponse_FooDescription"
+          },
+          "scopes": [
+            "https://www.googleapis.com/auth/userinfo.email"
+          ]
+        },
+        "update": {
+          "description": "update desc",
+          "httpMethod": "POST",
+          "id": "foo.foo.update",
+          "parameterOrder": [
+            "id"
+          ],
+          "parameters": {
+            "id": {
+              "description": "id desc",
+              "location": "path",
+              "required": true,
+              "type": "string"
+            }
+          },
+          "path": "foos/{id}",
+          "request": {
+            "$ref": "FooDescription",
+            "parameterName": "resource"
+          },
+          "response": {
+            "$ref": "FooDescription"
+          },
+          "scopes": [
+            "https://www.googleapis.com/auth/userinfo.email"
+          ]
+        }
+      }
+    }
+  },
+  "rootUrl": "https://discovery-test.appspot.com/api/",
+  "schemas": {
+    "CollectionResponse_FooDescription": {
+      "id": "CollectionResponse_FooDescription",
+      "properties": {
+        "items": {
+          "items": {
+            "$ref": "FooDescription"
+          },
+          "type": "array"
+        },
+        "nextPageToken": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "FooDescription": {
+      "id": "FooDescription",
+      "properties": {
+        "name": {
+          "description":"description of name",
+          "type": "string"
+        },
+        "value": {
+          "description":"description of value",
+          "format": "int32",
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "servicePath": "foo/v1/",
+  "title": "The Foo API",
+  "version": "v1"
+}

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

@@ -0,0 +1,46 @@
+/*
+ * 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.testing;
+
+import com.google.api.server.spi.config.ApiResourceProperty;
+
+/**
+ * Test resource type with descriptions.
+ */
+public class FooDescription {
+
+  @ApiResourceProperty(description = "description of name")
+  private String name;
+  private int value;
+  private String hidden;
+
+  public String getName() {
+    return name;
+  }
+
+  @ApiResourceProperty(description = "description of value")
+  public int getValue() {
+    return value;
+  }
+
+  private String getHidden() {
+    return hidden;
+  }
+
+  private void setHidden(String hidden) {
+    this.hidden = hidden;
+  }
+}

test-utils/src/main/java/com/google/api/server/spi/testing/FooDescriptionEndpoint.java

@@ -0,0 +1,61 @@
+/*
+ * 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.testing;
+
+import com.google.api.server.spi.config.Api;
+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.response.CollectionResponse;
+
+@Api(
+    name = "foo",
+    version = "v1",
+    audiences = {"audience"},
+    title = "The Foo API",
+    description = "Just Foo Things")
+public class FooDescriptionEndpoint {
+  @ApiMethod(name = "foo.create", description = "create desc", path = "foos/{id}",
+      httpMethod = HttpMethod.PUT)
+  public FooDescription createFoo(@Named("id") @Description("id desc") String id, FooDescription foo) {
+    return null;
+  }
+  @ApiMethod(name = "foo.get", description = "get desc", path = "foos/{id}",
+      httpMethod = HttpMethod.GET)
+  public FooDescription getFoo(@Named("id") @Description("id desc") String id) {
+    return null;
+  }
+  @ApiMethod(name = "foo.update", description = "update desc", path = "foos/{id}",
+      httpMethod = HttpMethod.POST)
+  public FooDescription updateFoo(@Named("id") @Description("id desc") String id, FooDescription foo) {
+    return null;
+  }
+  @ApiMethod(name = "foo.delete", description = "delete desc", path = "foos/{id}",
+      httpMethod = HttpMethod.DELETE)
+  public FooDescription deleteFoo(@Named("id") @Description("id desc") String id) {
+    return null;
+  }
+  @ApiMethod(name = "foo.list", description = "list desc", path = "foos",
+      httpMethod = HttpMethod.GET)
+  public CollectionResponse<FooDescription> listFoos(@Named("n") Integer n) {
+    return null;
+  }
+  @ApiMethod(name = "toplevel", path = "foos", httpMethod = HttpMethod.POST)
+  public CollectionResponse<FooDescription> toplevel() {
+    return null;
+  }
+}