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

Commit

Permalink
Add description in swagger file
Browse files Browse the repository at this point in the history
  • Loading branch information
@tangiel
Kevin Aldebert authored and tangiel committed Feb 8, 2018
1 parent 3dc726b commit 4959f33
Show file tree
Hide file tree
Showing 3 changed files with 300 additions and 23 deletions.
63 changes: 40 additions & 23 deletions endpoints-framework/src/main/java/com/google/api/server/spi/swagger/SwaggerGenerator.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
*/
package com.google.api.server.spi.swagger;

import com.google.api.server.spi.Constant;
import com.google.api.server.spi.EndpointMethod;
import com.google.api.server.spi.Strings;
import com.google.api.server.spi.TypeLoader;
Expand Down Expand Up @@ -149,20 +148,6 @@ public class SwaggerGenerator {
.put(DateAndTime.class, "date-time")
.put(Date.class, "date-time")
.build();
private static final ImmutableMap<FieldType, Property> FIELD_TYPE_TO_PROPERTY_MAP =
ImmutableMap.<FieldType, Property>builder()
.put(FieldType.BOOLEAN, new BooleanProperty())
.put(FieldType.BYTE_STRING, new ByteArrayProperty())
.put(FieldType.DATE, new DateProperty())
.put(FieldType.DATE_TIME, new DateTimeProperty())
.put(FieldType.DOUBLE, new DoubleProperty())
.put(FieldType.FLOAT, new FloatProperty())
.put(FieldType.INT8, new IntegerProperty())
.put(FieldType.INT16, new IntegerProperty())
.put(FieldType.INT32, new IntegerProperty())
.put(FieldType.INT64, new LongProperty())
.put(FieldType.STRING, new StringProperty())
.build();

private static final Function<ApiConfig, ApiKey> CONFIG_TO_ROOTLESS_KEY =
new Function<ApiConfig, ApiKey>() {
Expand Down Expand Up @@ -420,15 +405,47 @@ private Model convertToSwaggerSchema(Schema schema) {
}

private Property convertToSwaggerProperty(Field f) {
Property p = FIELD_TYPE_TO_PROPERTY_MAP.get(f.type());
if (p != null) {
return p;
} else if (f.type() == FieldType.OBJECT || f.type() == FieldType.ENUM) {
return new RefProperty(f.schemaReference().get().name());
} else if (f.type() == FieldType.ARRAY) {
return new ArrayProperty(convertToSwaggerProperty(f.arrayItemSchema()));
Property p = createProperty(f);
if (p == null) {
if (f.type() == FieldType.OBJECT || f.type() == FieldType.ENUM) {
p = new RefProperty(f.schemaReference().get().name());
} else if (f.type() == FieldType.ARRAY) {
p = new ArrayProperty(convertToSwaggerProperty(f.arrayItemSchema()));
} else {
throw new IllegalArgumentException("could not convert field " + f);
}
}
p.description(f.description());
return p;
}

private Property createProperty(Field f) {
switch (f.type()) {
case BOOLEAN:
return new BooleanProperty();
case BYTE_STRING:
return new ByteArrayProperty();
case DATE:
return new DateProperty();
case DATE_TIME:
return new DateTimeProperty();
case DOUBLE:
return new DoubleProperty();
case FLOAT:
return new FloatProperty();
case INT8:
return new IntegerProperty();
case INT16:
return new IntegerProperty();
case INT32:
return new IntegerProperty();
case INT64:
return new LongProperty();
case STRING:
return new StringProperty();
default:
return null;
}
throw new IllegalArgumentException("could not convert field " + f);
}

private static String getOperationId(ApiConfig apiConfig, ApiMethodConfig methodConfig) {
Expand Down
9 changes: 9 additions & 0 deletions ...oints-framework/src/test/java/com/google/api/server/spi/swagger/SwaggerGeneratorTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
import com.google.api.server.spi.testing.AbsolutePathEndpoint;
import com.google.api.server.spi.testing.ArrayEndpoint;
import com.google.api.server.spi.testing.EnumEndpoint;
import com.google.api.server.spi.testing.FooDescriptionEndpoint;
import com.google.api.server.spi.testing.FooEndpoint;
import com.google.api.server.spi.testing.LimitMetricsEndpoint;
import com.google.common.collect.ImmutableList;
Expand Down Expand Up @@ -162,6 +163,14 @@ public void testWriteSwagger_LimitMetricsEndpoint() throws Exception {
compareSwagger(expected, swagger);
}

@Test
public void testWriteSwagger_FooEndpointWithDescription() throws Exception {
ApiConfig config = configLoader.loadConfiguration(ServiceContext.create(), FooDescriptionEndpoint.class);
Swagger swagger = generator.writeSwagger(ImmutableList.of(config), false, context);
Swagger expected = readExpectedAsSwagger("foo_with_description_endpoint.swagger");
compareSwagger(expected, swagger);
}

private Swagger getSwagger(Class<?> serviceClass, SwaggerContext context, boolean internal)
throws Exception {
ApiConfig config = configLoader.loadConfiguration(ServiceContext.create(), serviceClass);
Expand Down
251 changes: 251 additions & 0 deletions ...rc/test/resources/com/google/api/server/spi/swagger/foo_with_description_endpoint.swagger
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,251 @@
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "swagger-test.appspot.com"
},
"host": "swagger-test.appspot.com",
"basePath": "/api",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/foo/v1/foos": {
"get": {
"description": "list desc",
"operationId": "FooListFoos",
"parameters": [
{
"name": "n",
"in": "query",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/CollectionResponse_FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
},
"post": {
"operationId": "FooToplevel",
"parameters": [],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/CollectionResponse_FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
}
},
"/foo/v1/foos/{id}": {
"get": {
"description": "get desc",
"operationId": "FooGetFoo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id desc",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
},
"post": {
"description": "update desc",
"operationId": "FooUpdateFoo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id desc",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
},
"put": {
"description": "create desc",
"operationId": "FooCreateFoo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id desc",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
},
"delete": {
"description": "delete desc",
"operationId": "FooDeleteFoo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id desc",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/FooDescription"
}
}
},
"security": [
{
"google_id_token-3a26ea04": []
},
{
"google_id_token_https-3a26ea04": []
}
]
}
}
},
"securityDefinitions": {
"google_id_token-3a26ea04": {
"type": "oauth2",
"authorizationUrl": "",
"flow": "implicit",
"x-google-issuer": "accounts.google.com",
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v1/certs",
"x-google-audiences": "audience"
},
"google_id_token_https-3a26ea04": {
"type": "oauth2",
"authorizationUrl": "",
"flow": "implicit",
"x-google-issuer": "https://accounts.google.com",
"x-google-jwks_uri": "https://www.googleapis.com/oauth2/v1/certs",
"x-google-audiences": "audience"
}
},
"definitions": {
"CollectionResponse_FooDescription": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/FooDescription"
}
},
"nextPageToken": {
"type": "string"
}
}
},
"FooDescription": {
"properties": {
"name": {
"description": "description of name",
"type": "string"
},
"value": {
"type": "integer",
"format": "int32",
"description": "description of value"
}
}
}
}
}

0 comments on commit 4959f33

Please sign in to comment.