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

Commit 4959f33

Browse files
Kevin Aldeberttangiel
Kevin Aldebert
authored and
tangiel
committed
Add description in swagger file
1 parent 3dc726b commit 4959f33

File tree

3 files changed

+300
-23
lines changed

3 files changed

+300
-23
lines changed

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

+40-23
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@
1515
*/
1616
package com.google.api.server.spi.swagger;
1717

18-
import com.google.api.server.spi.Constant;
1918
import com.google.api.server.spi.EndpointMethod;
2019
import com.google.api.server.spi.Strings;
2120
import com.google.api.server.spi.TypeLoader;
@@ -149,20 +148,6 @@ public class SwaggerGenerator {
149148
.put(DateAndTime.class, "date-time")
150149
.put(Date.class, "date-time")
151150
.build();
152-
private static final ImmutableMap<FieldType, Property> FIELD_TYPE_TO_PROPERTY_MAP =
153-
ImmutableMap.<FieldType, Property>builder()
154-
.put(FieldType.BOOLEAN, new BooleanProperty())
155-
.put(FieldType.BYTE_STRING, new ByteArrayProperty())
156-
.put(FieldType.DATE, new DateProperty())
157-
.put(FieldType.DATE_TIME, new DateTimeProperty())
158-
.put(FieldType.DOUBLE, new DoubleProperty())
159-
.put(FieldType.FLOAT, new FloatProperty())
160-
.put(FieldType.INT8, new IntegerProperty())
161-
.put(FieldType.INT16, new IntegerProperty())
162-
.put(FieldType.INT32, new IntegerProperty())
163-
.put(FieldType.INT64, new LongProperty())
164-
.put(FieldType.STRING, new StringProperty())
165-
.build();
166151

167152
private static final Function<ApiConfig, ApiKey> CONFIG_TO_ROOTLESS_KEY =
168153
new Function<ApiConfig, ApiKey>() {
@@ -420,15 +405,47 @@ private Model convertToSwaggerSchema(Schema schema) {
420405
}
421406

422407
private Property convertToSwaggerProperty(Field f) {
423-
Property p = FIELD_TYPE_TO_PROPERTY_MAP.get(f.type());
424-
if (p != null) {
425-
return p;
426-
} else if (f.type() == FieldType.OBJECT || f.type() == FieldType.ENUM) {
427-
return new RefProperty(f.schemaReference().get().name());
428-
} else if (f.type() == FieldType.ARRAY) {
429-
return new ArrayProperty(convertToSwaggerProperty(f.arrayItemSchema()));
408+
Property p = createProperty(f);
409+
if (p == null) {
410+
if (f.type() == FieldType.OBJECT || f.type() == FieldType.ENUM) {
411+
p = new RefProperty(f.schemaReference().get().name());
412+
} else if (f.type() == FieldType.ARRAY) {
413+
p = new ArrayProperty(convertToSwaggerProperty(f.arrayItemSchema()));
414+
} else {
415+
throw new IllegalArgumentException("could not convert field " + f);
416+
}
417+
}
418+
p.description(f.description());
419+
return p;
420+
}
421+
422+
private Property createProperty(Field f) {
423+
switch (f.type()) {
424+
case BOOLEAN:
425+
return new BooleanProperty();
426+
case BYTE_STRING:
427+
return new ByteArrayProperty();
428+
case DATE:
429+
return new DateProperty();
430+
case DATE_TIME:
431+
return new DateTimeProperty();
432+
case DOUBLE:
433+
return new DoubleProperty();
434+
case FLOAT:
435+
return new FloatProperty();
436+
case INT8:
437+
return new IntegerProperty();
438+
case INT16:
439+
return new IntegerProperty();
440+
case INT32:
441+
return new IntegerProperty();
442+
case INT64:
443+
return new LongProperty();
444+
case STRING:
445+
return new StringProperty();
446+
default:
447+
return null;
430448
}
431-
throw new IllegalArgumentException("could not convert field " + f);
432449
}
433450

434451
private static String getOperationId(ApiConfig apiConfig, ApiMethodConfig methodConfig) {

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

+9
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
import com.google.api.server.spi.testing.AbsolutePathEndpoint;
3535
import com.google.api.server.spi.testing.ArrayEndpoint;
3636
import com.google.api.server.spi.testing.EnumEndpoint;
37+
import com.google.api.server.spi.testing.FooDescriptionEndpoint;
3738
import com.google.api.server.spi.testing.FooEndpoint;
3839
import com.google.api.server.spi.testing.LimitMetricsEndpoint;
3940
import com.google.common.collect.ImmutableList;
@@ -162,6 +163,14 @@ public void testWriteSwagger_LimitMetricsEndpoint() throws Exception {
162163
compareSwagger(expected, swagger);
163164
}
164165

166+
@Test
167+
public void testWriteSwagger_FooEndpointWithDescription() throws Exception {
168+
ApiConfig config = configLoader.loadConfiguration(ServiceContext.create(), FooDescriptionEndpoint.class);
169+
Swagger swagger = generator.writeSwagger(ImmutableList.of(config), false, context);
170+
Swagger expected = readExpectedAsSwagger("foo_with_description_endpoint.swagger");
171+
compareSwagger(expected, swagger);
172+
}
173+
165174
private Swagger getSwagger(Class<?> serviceClass, SwaggerContext context, boolean internal)
166175
throws Exception {
167176
ApiConfig config = configLoader.loadConfiguration(ServiceContext.create(), serviceClass);

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

+251
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"version": "1.0.0",
5+
"title": "swagger-test.appspot.com"
6+
},
7+
"host": "swagger-test.appspot.com",
8+
"basePath": "/api",
9+
"schemes": [
10+
"https"
11+
],
12+
"consumes": [
13+
"application/json"
14+
],
15+
"produces": [
16+
"application/json"
17+
],
18+
"paths": {
19+
"/foo/v1/foos": {
20+
"get": {
21+
"description": "list desc",
22+
"operationId": "FooListFoos",
23+
"parameters": [
24+
{
25+
"name": "n",
26+
"in": "query",
27+
"required": true,
28+
"type": "integer",
29+
"format": "int32"
30+
}
31+
],
32+
"responses": {
33+
"200": {
34+
"description": "A successful response",
35+
"schema": {
36+
"$ref": "#/definitions/CollectionResponse_FooDescription"
37+
}
38+
}
39+
},
40+
"security": [
41+
{
42+
"google_id_token-3a26ea04": []
43+
},
44+
{
45+
"google_id_token_https-3a26ea04": []
46+
}
47+
]
48+
},
49+
"post": {
50+
"operationId": "FooToplevel",
51+
"parameters": [],
52+
"responses": {
53+
"200": {
54+
"description": "A successful response",
55+
"schema": {
56+
"$ref": "#/definitions/CollectionResponse_FooDescription"
57+
}
58+
}
59+
},
60+
"security": [
61+
{
62+
"google_id_token-3a26ea04": []
63+
},
64+
{
65+
"google_id_token_https-3a26ea04": []
66+
}
67+
]
68+
}
69+
},
70+
"/foo/v1/foos/{id}": {
71+
"get": {
72+
"description": "get desc",
73+
"operationId": "FooGetFoo",
74+
"parameters": [
75+
{
76+
"name": "id",
77+
"in": "path",
78+
"description": "id desc",
79+
"required": true,
80+
"type": "string"
81+
}
82+
],
83+
"responses": {
84+
"200": {
85+
"description": "A successful response",
86+
"schema": {
87+
"$ref": "#/definitions/FooDescription"
88+
}
89+
}
90+
},
91+
"security": [
92+
{
93+
"google_id_token-3a26ea04": []
94+
},
95+
{
96+
"google_id_token_https-3a26ea04": []
97+
}
98+
]
99+
},
100+
"post": {
101+
"description": "update desc",
102+
"operationId": "FooUpdateFoo",
103+
"parameters": [
104+
{
105+
"name": "id",
106+
"in": "path",
107+
"description": "id desc",
108+
"required": true,
109+
"type": "string"
110+
},
111+
{
112+
"in": "body",
113+
"name": "body",
114+
"required": false,
115+
"schema": {
116+
"$ref": "#/definitions/FooDescription"
117+
}
118+
}
119+
],
120+
"responses": {
121+
"200": {
122+
"description": "A successful response",
123+
"schema": {
124+
"$ref": "#/definitions/FooDescription"
125+
}
126+
}
127+
},
128+
"security": [
129+
{
130+
"google_id_token-3a26ea04": []
131+
},
132+
{
133+
"google_id_token_https-3a26ea04": []
134+
}
135+
]
136+
},
137+
"put": {
138+
"description": "create desc",
139+
"operationId": "FooCreateFoo",
140+
"parameters": [
141+
{
142+
"name": "id",
143+
"in": "path",
144+
"description": "id desc",
145+
"required": true,
146+
"type": "string"
147+
},
148+
{
149+
"in": "body",
150+
"name": "body",
151+
"required": false,
152+
"schema": {
153+
"$ref": "#/definitions/FooDescription"
154+
}
155+
}
156+
],
157+
"responses": {
158+
"200": {
159+
"description": "A successful response",
160+
"schema": {
161+
"$ref": "#/definitions/FooDescription"
162+
}
163+
}
164+
},
165+
"security": [
166+
{
167+
"google_id_token-3a26ea04": []
168+
},
169+
{
170+
"google_id_token_https-3a26ea04": []
171+
}
172+
]
173+
},
174+
"delete": {
175+
"description": "delete desc",
176+
"operationId": "FooDeleteFoo",
177+
"parameters": [
178+
{
179+
"name": "id",
180+
"in": "path",
181+
"description": "id desc",
182+
"required": true,
183+
"type": "string"
184+
}
185+
],
186+
"responses": {
187+
"200": {
188+
"description": "A successful response",
189+
"schema": {
190+
"$ref": "#/definitions/FooDescription"
191+
}
192+
}
193+
},
194+
"security": [
195+
{
196+
"google_id_token-3a26ea04": []
197+
},
198+
{
199+
"google_id_token_https-3a26ea04": []
200+
}
201+
]
202+
}
203+
}
204+
},
205+
"securityDefinitions": {
206+
"google_id_token-3a26ea04": {
207+
"type": "oauth2",
208+
"authorizationUrl": "",
209+
"flow": "implicit",
210+
"x-google-issuer": "accounts.google.com",
211+
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v1/certs",
212+
"x-google-audiences": "audience"
213+
},
214+
"google_id_token_https-3a26ea04": {
215+
"type": "oauth2",
216+
"authorizationUrl": "",
217+
"flow": "implicit",
218+
"x-google-issuer": "https://accounts.google.com",
219+
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v1/certs",
220+
"x-google-audiences": "audience"
221+
}
222+
},
223+
"definitions": {
224+
"CollectionResponse_FooDescription": {
225+
"properties": {
226+
"items": {
227+
"type": "array",
228+
"items": {
229+
"$ref": "#/definitions/FooDescription"
230+
}
231+
},
232+
"nextPageToken": {
233+
"type": "string"
234+
}
235+
}
236+
},
237+
"FooDescription": {
238+
"properties": {
239+
"name": {
240+
"description": "description of name",
241+
"type": "string"
242+
},
243+
"value": {
244+
"type": "integer",
245+
"format": "int32",
246+
"description": "description of value"
247+
}
248+
}
249+
}
250+
}
251+
}

0 commit comments

Comments
 (0)