Skip to content
This repository was archived by the owner on Jun 30, 2023. It is now read-only.

Commit 98145e9

Browse files
urmuzovurmuzov
committed
Discovery: documentationLink added, @description for enum constants and fields
1 parent efe63f3 commit 98145e9

4 files changed

Lines changed: 41 additions & 4 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
/**
2424
* Annotation to specify the description of an API parameter.
2525
*/
26-
@Target(ElementType.PARAMETER)
26+
@Target({ElementType.PARAMETER, ElementType.FIELD})
2727
@Retention(RetentionPolicy.RUNTIME)
2828
public @interface Description {
2929
/**

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ public abstract class Schema {
1616
/** The name of the schema. */
1717
public abstract String name();
1818
public abstract String type();
19+
@Nullable public abstract String description();
1920

2021
/** A map from field names to fields for the schema. */
2122
public abstract ImmutableSortedMap<String, Field> fields();
@@ -44,6 +45,7 @@ public abstract static class Builder {
4445

4546
public abstract Builder setName(String name);
4647
public abstract Builder setType(String type);
48+
@Nullable public abstract Builder setDescription(String description);
4749
public abstract Builder setFields(ImmutableSortedMap<String, Field> fields);
4850
public Builder addField(String name, Field field) {
4951
fieldsBuilder.put(name, field);
@@ -76,6 +78,8 @@ public static abstract class Field {
7678
/** The type classification of the field. */
7779
public abstract FieldType type();
7880

81+
@Nullable public abstract String description();
82+
7983
/**
8084
* If {@link #type()} is {@link FieldType#OBJECT}, a reference to the schema type that the field
8185
* refers to.
@@ -97,6 +101,7 @@ public static Builder builder() {
97101
public abstract static class Builder {
98102
public abstract Builder setName(String name);
99103
public abstract Builder setType(FieldType type);
104+
@Nullable public abstract Builder setDescription(String description);
100105
public abstract Builder setSchemaReference(SchemaReference ref);
101106
public abstract Builder setArrayItemSchema(Field schema);
102107
public abstract Field build();

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

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import com.google.api.client.util.Maps;
44
import com.google.api.server.spi.TypeLoader;
5+
import com.google.api.server.spi.config.Description;
56
import com.google.api.server.spi.config.ResourcePropertySchema;
67
import com.google.api.server.spi.config.ResourceSchema;
78
import com.google.api.server.spi.config.annotationreader.ApiAnnotationIntrospector;
@@ -154,8 +155,13 @@ private Schema getOrCreateTypeForConfig(
154155
.setName(Types.getSimpleName(type, config.getSerializationConfig()))
155156
.setType("string");
156157
for (Object enumConstant : type.getRawType().getEnumConstants()) {
157-
builder.addEnumValue(enumConstant.toString());
158-
builder.addEnumDescription("");
158+
builder.addEnumValue(((Enum) enumConstant).name());
159+
try {
160+
final Description description = enumConstant.getClass().getField(((Enum) enumConstant).name()).getAnnotation(Description.class);
161+
builder.addEnumDescription(description == null ? "" : description.value());
162+
} catch (NoSuchFieldException ex) {
163+
builder.addEnumDescription("");
164+
}
159165
}
160166
schema = builder.build();
161167
typesForConfig.put(type, schema);
@@ -189,12 +195,24 @@ private Schema createBeanSchema(
189195
Schema.Builder builder = Schema.builder()
190196
.setName(Types.getSimpleName(type, config.getSerializationConfig()))
191197
.setType("object");
198+
final Description description = type.getRawType().getAnnotation(Description.class);
199+
if (description != null) {
200+
builder.setDescription(description.value());
201+
}
192202
ResourceSchema schema = resourceSchemaProvider.getResourceSchema(type, config);
193203
for (Entry<String, ResourcePropertySchema> entry : schema.getProperties().entrySet()) {
194204
String propertyName = entry.getKey();
195205
TypeToken<?> propertyType = entry.getValue().getType();
196206
if (propertyType != null) {
197207
Field.Builder fieldBuilder = Field.builder().setName(propertyName);
208+
try {
209+
Description propertyDescription = type.getRawType().getField(propertyName).getAnnotation(Description.class);
210+
if (propertyDescription != null) {
211+
fieldBuilder.setDescription(propertyDescription.value());
212+
}
213+
} catch (NoSuchFieldException e) {
214+
// ignore
215+
}
198216
fillInFieldInformation(fieldBuilder, propertyType, typesForConfig, config);
199217
builder.addField(propertyName, fieldBuilder.build());
200218
}

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import com.google.api.server.spi.ObjectMapperUtil;
2121
import com.google.api.server.spi.Strings;
2222
import com.google.api.server.spi.TypeLoader;
23+
import com.google.api.server.spi.config.Description;
2324
import com.google.api.server.spi.config.annotationreader.ApiAnnotationIntrospector;
2425
import com.google.api.server.spi.config.model.ApiConfig;
2526
import com.google.api.server.spi.config.model.ApiKey;
@@ -151,6 +152,9 @@ private RestDescription writeApi(ApiKey apiKey, Iterable<ApiConfig> apiConfigs,
151152
if (config.getDescription() != null) {
152153
doc.setDescription(config.getDescription());
153154
}
155+
if (config.getDocumentationLink() != null) {
156+
doc.setDocumentationLink(config.getDocumentationLink());
157+
}
154158
if (config.getTitle() != null) {
155159
doc.setTitle(config.getTitle());
156160
}
@@ -227,6 +231,9 @@ private JsonSchema convertToDiscoverySchema(Schema schema) {
227231
}
228232
docSchema.setProperties(fields);
229233
}
234+
if (schema.description() != null) {
235+
docSchema.setDescription(schema.description());
236+
}
230237
if (!schema.enumValues().isEmpty()) {
231238
docSchema.setEnum(new ArrayList<>(schema.enumValues()));
232239
docSchema.setEnumDescriptions(new ArrayList<>(schema.enumDescriptions()));
@@ -240,6 +247,7 @@ private JsonSchema convertToDiscoverySchema(Field f) {
240247
}
241248
JsonSchema fieldSchema = new JsonSchema()
242249
.setType(f.type().getDiscoveryType())
250+
.setDescription(f.description())
243251
.setFormat(f.type().getDiscoveryFormat());
244252
if (f.type() == FieldType.ARRAY) {
245253
fieldSchema.setItems(convertToDiscoverySchema(f.arrayItemSchema()));
@@ -325,7 +333,12 @@ private JsonSchema convertMethodParameter(
325333
List<String> enumDescriptions = Lists.newArrayList();
326334
for (Object enumConstant : type.getRawType().getEnumConstants()) {
327335
enumValues.add(enumConstant.toString());
328-
enumDescriptions.add(""); // not current supported in annotations
336+
try {
337+
final Description description = enumConstant.getClass().getField(((Enum) enumConstant).name()).getAnnotation(Description.class);
338+
enumDescriptions.add(description == null ? "" : description.value());
339+
} catch (NoSuchFieldException ex) {
340+
enumDescriptions.add("");
341+
}
329342
}
330343
schema.setEnum(enumValues);
331344
schema.setEnumDescriptions(enumDescriptions);
@@ -386,6 +399,7 @@ private DirectoryList generateDirectory(Map<ApiKey, RestDescription> discoveryDo
386399
.setDescription(doc.getDescription())
387400
.setDiscoveryLink("." + relativePath)
388401
.setDiscoveryRestUrl(context.getApiRoot() + "/discovery/v1" + relativePath)
402+
.setDocumentationLink(doc.getDocumentationLink())
389403
.setIcons(new Icons()
390404
.setX16("http://www.google.com/images/icons/product/search-16.gif")
391405
.setX32("http://www.google.com/images/icons/product/search-32.gif"))

0 commit comments

Comments
 (0)