From 2867cbbd1f578468270bacee5249d92670ed392d Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Thu, 15 Oct 2015 22:16:42 -0400 Subject: [PATCH 1/7] added example value support for post params, #1500 --- .../java/io/swagger/annotations/ApiParam.java | 13 +++++ .../java/io/swagger/annotations/Example.java | 47 +++++++++++++++++++ .../swagger/annotations/ExampleProperty.java | 47 +++++++++++++++++++ .../io/swagger/util/ParameterProcessor.java | 21 +++++++++ .../java/io/swagger/SimpleScannerTest.java | 33 ++++--------- .../resources/ClassWithExamplePost.java | 18 +++++++ .../models/parameters/BodyParameter.java | 26 ++++++++++ 7 files changed, 180 insertions(+), 25 deletions(-) create mode 100644 modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java create mode 100644 modules/swagger-annotations/src/main/java/io/swagger/annotations/ExampleProperty.java create mode 100644 modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java index a781cb9946..dc2b02a9b5 100644 --- a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java @@ -92,4 +92,17 @@ * Hides the parameter from the list of parameters. */ boolean hidden() default false; + + /** + * a single example for non-body type parameters + * + * @return + */ + String example() default ""; + + /** + * Examples for the parameter. Applies only to BodyParameters + * @return + */ + Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = "")); } diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java new file mode 100644 index 0000000000..ebe9003d98 --- /dev/null +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java @@ -0,0 +1,47 @@ +/** + * Copyright 2015 SmartBear Software + *

+ * 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 io.swagger.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * An optionally named list of example properties. + * + * @since 1.5.4 + */ +@Target(ElementType.ANNOTATION_TYPE) +@Retention(RetentionPolicy.RUNTIME) +public @interface Example { + + /** + * An option name for these examples. + * + * @return an option name for these examples - will be prefixed with "x-" + */ + String name() default ""; + + /** + * The examples properties. + * + * @return the actual extension properties + * @see ExampleProperty + */ + ExampleProperty[] value(); +} diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ExampleProperty.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ExampleProperty.java new file mode 100644 index 0000000000..6faa45182d --- /dev/null +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ExampleProperty.java @@ -0,0 +1,47 @@ +/** + * Copyright 2015 SmartBear Software + *

+ * 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 io.swagger.annotations; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * A mediaType/value property within a Swagger example + * + * @see Example + * @since 1.5.4 + */ +@Target(ElementType.ANNOTATION_TYPE) +@Retention(RetentionPolicy.RUNTIME) +public @interface ExampleProperty { + + /** + * The name of the property. + * + * @return the name of the property + */ + String mediaType() default "default"; + + /** + * The value of the example. + * + * @return the value of the example + */ + String value(); +} diff --git a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java index b148fc6791..6e3350b3f5 100644 --- a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java +++ b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java @@ -2,6 +2,8 @@ import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiParam; +import io.swagger.annotations.Example; +import io.swagger.annotations.ExampleProperty; import io.swagger.converter.ModelConverters; import io.swagger.models.Model; import io.swagger.models.Swagger; @@ -103,6 +105,23 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T // must be a body param BodyParameter bp = new BodyParameter(); + if(helper.getApiParam() != null) { + ParamWrapper pw = helper.getApiParam(); + + if(pw instanceof ApiParamWrapper) { + ApiParamWrapper apiParam = (ApiParamWrapper) pw; + Example example = apiParam.getExample(); + if(example != null && example.value() != null) { + for (ExampleProperty ex : example.value()) { + String mediaType = ex.mediaType(); + String value = ex.value(); + if (!mediaType.isEmpty() && !value.isEmpty()) { + bp.example(mediaType.trim(), value.trim()); + } + } + } + } + } bp.setRequired(param.isRequired()); bp.setName(StringUtils.isNotEmpty(param.getName()) ? param.getName() : "body"); @@ -341,6 +360,8 @@ public ApiParam getAnnotation() { public boolean isHidden() { return apiParam.hidden(); } + + public Example getExample() { return apiParam.examples();}; } /** diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java index a2dcbeb249..c4887d63dc 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java @@ -28,32 +28,9 @@ import io.swagger.models.properties.Property; import io.swagger.models.properties.RefProperty; import io.swagger.models.properties.StringProperty; -import io.swagger.resources.HiddenResource; -import io.swagger.resources.Resource1041; -import io.swagger.resources.Resource1073; -import io.swagger.resources.Resource1085; -import io.swagger.resources.Resource653; -import io.swagger.resources.Resource841; -import io.swagger.resources.Resource877; -import io.swagger.resources.Resource937; -import io.swagger.resources.ResourceWithApiOperationCode; -import io.swagger.resources.ResourceWithApiResponseResponseContainer; -import io.swagger.resources.ResourceWithBodyParams; -import io.swagger.resources.ResourceWithEmptyModel; -import io.swagger.resources.ResourceWithEnums; -import io.swagger.resources.ResourceWithInnerClass; -import io.swagger.resources.ResourceWithMapReturnValue; -import io.swagger.resources.ResourceWithRanges; -import io.swagger.resources.ResourceWithResponse; -import io.swagger.resources.ResourceWithResponseHeaders; -import io.swagger.resources.ResourceWithTypedResponses; -import io.swagger.resources.ResourceWithVoidReturns; -import io.swagger.resources.SimpleResource; -import io.swagger.resources.SimpleResourceWithoutAnnotations; -import io.swagger.resources.SimpleSelfReferencingSubResource; -import io.swagger.resources.TaggedResource; -import io.swagger.resources.NicknamedOperation; +import io.swagger.resources.*; +import io.swagger.util.Json; import org.testng.annotations.Test; import java.util.ArrayList; @@ -541,4 +518,10 @@ public void scanResourceWithApiOperationNickname() { assertEquals(op.getOperationId(), "getMyNicknameTest"); } + + @Test(description = "scan a resource with custom operation nickname") + public void scanClassWithExamplePost() { + Swagger swagger = getSwagger(ClassWithExamplePost.class); + Json.prettyPrint(swagger); + } } diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java new file mode 100644 index 0000000000..f5207d6ebd --- /dev/null +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java @@ -0,0 +1,18 @@ +package io.swagger.resources; + +import io.swagger.annotations.*; + +import javax.ws.rs.POST; +import javax.ws.rs.Path; +import java.util.ArrayList; + +@Api("/external/info/") +@Path("external/info/") +public class ClassWithExamplePost { + @ApiOperation(value = "test.") + @POST + public void postTest(@ApiParam(value = "test", + examples = @Example(value = {@ExampleProperty(mediaType="fun", value="bar")})) ArrayList tenantId) { + return; + } +} diff --git a/modules/swagger-models/src/main/java/io/swagger/models/parameters/BodyParameter.java b/modules/swagger-models/src/main/java/io/swagger/models/parameters/BodyParameter.java index 38150f5c54..20df1904df 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/parameters/BodyParameter.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/parameters/BodyParameter.java @@ -1,9 +1,14 @@ package io.swagger.models.parameters; +import com.fasterxml.jackson.annotation.JsonProperty; import io.swagger.models.Model; +import java.util.HashMap; +import java.util.Map; + public class BodyParameter extends AbstractParameter implements Parameter { Model schema; + Map examples; public BodyParameter() { super.setIn("body"); @@ -14,6 +19,11 @@ public BodyParameter schema(Model schema) { return this; } + public BodyParameter example(String mediaType, String value) { + this.addExample(mediaType, value); + return this; + } + public BodyParameter description(String description) { this.setDescription(description); return this; @@ -32,6 +42,22 @@ public void setSchema(Model schema) { this.schema = schema; } + public void addExample(String mediaType, String value) { + if(examples == null) { + examples = new HashMap(); + } + examples.put(mediaType, value); + } + + @JsonProperty("x-examples") + public Map getExamples() { + return examples; + } + + public void setExamples(Map examples) { + this.examples = examples; + } + @Override public int hashCode() { final int prime = 31; From 4a103856ed34e8af850cd6519094082c0b5631e0 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Thu, 15 Oct 2015 22:22:24 -0400 Subject: [PATCH 2/7] updated test --- .../src/test/java/io/swagger/SimpleScannerTest.java | 8 +++++++- .../java/io/swagger/resources/ClassWithExamplePost.java | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java index c4887d63dc..ff3cd69936 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java @@ -522,6 +522,12 @@ public void scanResourceWithApiOperationNickname() { @Test(description = "scan a resource with custom operation nickname") public void scanClassWithExamplePost() { Swagger swagger = getSwagger(ClassWithExamplePost.class); - Json.prettyPrint(swagger); + Parameter param = swagger.getPaths().get("/external/info").getPost().getParameters().get(0); + Json.prettyPrint(param); + BodyParameter bp = (BodyParameter) param; + assertNotNull(bp.getExamples()); + assertTrue(bp.getExamples().size() == 1); + String value = bp.getExamples().get("foo"); + assertEquals("bar", value); } } diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java index f5207d6ebd..15272565b4 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java @@ -12,7 +12,7 @@ public class ClassWithExamplePost { @ApiOperation(value = "test.") @POST public void postTest(@ApiParam(value = "test", - examples = @Example(value = {@ExampleProperty(mediaType="fun", value="bar")})) ArrayList tenantId) { + examples = @Example(value = {@ExampleProperty(mediaType="foo", value="bar")})) ArrayList tenantId) { return; } } From 62c100f33a54d7688e859cd011abb89a907e02ef Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 16 Oct 2015 12:40:17 -0400 Subject: [PATCH 3/7] added example support for non-body params, implicits --- .../swagger/annotations/ApiImplicitParam.java | 18 ++++++++ .../java/io/swagger/annotations/ApiParam.java | 5 ++ .../io/swagger/util/ParameterProcessor.java | 38 ++++++++++++++- .../java/io/swagger/SimpleScannerTest.java | 38 +++++++++++++-- .../resources/ClassWithExamplePost.java | 46 +++++++++++++++++-- .../AbstractSerializableParameter.java | 16 +++++++ 6 files changed, 152 insertions(+), 9 deletions(-) diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java index a93bf28fe5..581151343c 100644 --- a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java @@ -109,4 +109,22 @@ * Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}. */ String paramType() default ""; + + /** + * a single example for non-body type parameters + * + * @since 1.5.4 + * + * @return + */ + String example() default ""; + + /** + * Examples for the parameter. Applies only to BodyParameters + * + * @since 1.5.4 + * + * @return + */ + Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = "")); } diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java index dc2b02a9b5..7ec39194fc 100644 --- a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java @@ -96,12 +96,17 @@ /** * a single example for non-body type parameters * + * @since 1.5.4 + * * @return */ String example() default ""; /** * Examples for the parameter. Applies only to BodyParameters + * + * @since 1.5.4 + * * @return */ Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = "")); diff --git a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java index 6e3350b3f5..97c4d0d375 100644 --- a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java +++ b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java @@ -52,12 +52,18 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T if (StringUtils.isNotEmpty(param.getDescription())) { p.setDescription(param.getDescription()); } + if (StringUtils.isNotEmpty(param.getExample())) { + p.setExample(param.getExample()); + } if (StringUtils.isNotEmpty(param.getAccess())) { p.setAccess(param.getAccess()); } if (StringUtils.isNotEmpty(param.getDataType())) { p.setType(param.getDataType()); } + if (StringUtils.isNotEmpty(param.getExample())) { + p.setType(param.getExample()); + } if (helper.getMinItems() != null) { p.setMinItems(helper.getMinItems()); } @@ -82,6 +88,7 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T args.put(PropertyBuilder.PropertyId.MAXIMUM, p.getMaximum()); p.setMaximum(null); args.put(PropertyBuilder.PropertyId.EXCLUSIVE_MAXIMUM, p.isExclusiveMaximum()); + args.put(PropertyBuilder.PropertyId.EXAMPLE, p.getExample()); p.setExclusiveMaximum(null); Property items = PropertyBuilder.build(p.getType(), p.getFormat(), args); p.type(ArrayProperty.TYPE).format(null).items(items); @@ -110,7 +117,20 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T if(pw instanceof ApiParamWrapper) { ApiParamWrapper apiParam = (ApiParamWrapper) pw; - Example example = apiParam.getExample(); + Example example = apiParam.getExamples(); + if(example != null && example.value() != null) { + for (ExampleProperty ex : example.value()) { + String mediaType = ex.mediaType(); + String value = ex.value(); + if (!mediaType.isEmpty() && !value.isEmpty()) { + bp.example(mediaType.trim(), value.trim()); + } + } + } + } + else if(pw instanceof ApiImplicitParamWrapper) { + ApiImplicitParamWrapper apiParam = (ApiImplicitParamWrapper) pw; + Example example = apiParam.getExamples(); if(example != null && example.value() != null) { for (ExampleProperty ex : example.value()) { String mediaType = ex.mediaType(); @@ -198,6 +218,8 @@ public interface ParamWrapper { T getAnnotation(); boolean isHidden(); + + String getExample(); } /** @@ -361,7 +383,12 @@ public boolean isHidden() { return apiParam.hidden(); } - public Example getExample() { return apiParam.examples();}; + @Override + public String getExample() { + return apiParam.example(); + }; + + public Example getExamples() { return apiParam.examples();}; } /** @@ -429,5 +456,12 @@ public ApiImplicitParam getAnnotation() { public boolean isHidden() { return false; } + + @Override + public String getExample() { + return apiParam.example(); + }; + + public Example getExamples() { return apiParam.examples();}; } } diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java index ff3cd69936..3f3a372c18 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java @@ -519,15 +519,45 @@ public void scanResourceWithApiOperationNickname() { assertEquals(op.getOperationId(), "getMyNicknameTest"); } - @Test(description = "scan a resource with custom operation nickname") + @Test(description = "scan a resource with operation post example") public void scanClassWithExamplePost() { Swagger swagger = getSwagger(ClassWithExamplePost.class); Parameter param = swagger.getPaths().get("/external/info").getPost().getParameters().get(0); - Json.prettyPrint(param); BodyParameter bp = (BodyParameter) param; assertNotNull(bp.getExamples()); assertTrue(bp.getExamples().size() == 1); - String value = bp.getExamples().get("foo"); - assertEquals("bar", value); + String value = bp.getExamples().get("application/json"); + assertEquals("[\"a\",\"b\"]", value); + } + + @Test(description = "scan a resource with operation implicit post example") + public void scanClassWithImplicitExamplePost() { + Swagger swagger = getSwagger(ClassWithExamplePost.class); + Parameter param = swagger.getPaths().get("/external/info2").getPost().getParameters().get(0); + BodyParameter bp = (BodyParameter) param; + assertNotNull(bp.getExamples()); + assertTrue(bp.getExamples().size() == 1); + String value = bp.getExamples().get("application/json"); + assertEquals("[\"a\",\"b\"]", value); + } + + @Test(description = "scan a resource with query param example") + public void scanClassWithExampleQuery() { + Swagger swagger = getSwagger(ClassWithExamplePost.class); + Parameter param = swagger.getPaths().get("/external/info").getGet().getParameters().get(0); + QueryParameter bp = (QueryParameter) param; + assertNotNull(bp.getExample()); + String value = bp.getExample(); + assertEquals("a,b,c", value); + } + + @Test(description = "scan a resource with implicit operation query example") + public void scanClassWithImplicitExampleQuery() { + Swagger swagger = getSwagger(ClassWithExamplePost.class); + Parameter param = swagger.getPaths().get("/external/info2").getGet().getParameters().get(0); + QueryParameter bp = (QueryParameter) param; + assertNotNull(bp.getExample()); + String value = bp.getExample(); + assertEquals("77", value); } } diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java index 15272565b4..3fc59700a7 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java @@ -2,17 +2,57 @@ import io.swagger.annotations.*; +import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; +import javax.ws.rs.QueryParam; import java.util.ArrayList; @Api("/external/info/") -@Path("external/info/") public class ClassWithExamplePost { - @ApiOperation(value = "test.") + @ApiOperation(value = "test") @POST + @Path("external/info") public void postTest(@ApiParam(value = "test", - examples = @Example(value = {@ExampleProperty(mediaType="foo", value="bar")})) ArrayList tenantId) { + examples = @Example(value = { + @ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]") + })) ArrayList tenantId) { + return; + } + + @ApiOperation(value = "test") + @POST + @Path("external/info2") + @ApiImplicitParams({ + @ApiImplicitParam( + paramType = "body", + name = "myPody", + dataType = "[Ljava.lang.String;", + examples = @Example(value = { + @ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]")})) + }) + public void implicitPostTest() { + return; + } + + @ApiOperation(value = "test") + @GET + @Path("external/info") + public void queryExample(@ApiParam(value = "test", + example = "a,b,c") @QueryParam("tenantId") ArrayList tenantId) { + return; + } + + @ApiOperation(value = "test") + @GET + @Path("external/info2") + @ApiImplicitParams({ + @ApiImplicitParam( + paramType = "query", + name = "myId", + dataType = "java.lang.Long", + example = "77") }) + public void implicitQueryExample() { return; } } diff --git a/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java b/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java index 2ebc5d126e..3df0d1ab87 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java @@ -1,6 +1,7 @@ package io.swagger.models.parameters; import com.fasterxml.jackson.annotation.JsonIgnore; +import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.annotation.JsonPropertyOrder; import org.slf4j.Logger; @@ -28,6 +29,7 @@ public abstract class AbstractSerializableParameter Date: Fri, 16 Oct 2015 18:15:46 -0700 Subject: [PATCH 4/7] reformatted --- .../io/swagger/util/ParameterProcessor.java | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java index 97c4d0d375..014560f3f5 100644 --- a/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java +++ b/modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java @@ -112,13 +112,13 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T // must be a body param BodyParameter bp = new BodyParameter(); - if(helper.getApiParam() != null) { + if (helper.getApiParam() != null) { ParamWrapper pw = helper.getApiParam(); - if(pw instanceof ApiParamWrapper) { + if (pw instanceof ApiParamWrapper) { ApiParamWrapper apiParam = (ApiParamWrapper) pw; Example example = apiParam.getExamples(); - if(example != null && example.value() != null) { + if (example != null && example.value() != null) { for (ExampleProperty ex : example.value()) { String mediaType = ex.mediaType(); String value = ex.value(); @@ -127,11 +127,10 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T } } } - } - else if(pw instanceof ApiImplicitParamWrapper) { + } else if (pw instanceof ApiImplicitParamWrapper) { ApiImplicitParamWrapper apiParam = (ApiImplicitParamWrapper) pw; Example example = apiParam.getExamples(); - if(example != null && example.value() != null) { + if (example != null && example.value() != null) { for (ExampleProperty ex : example.value()) { String mediaType = ex.mediaType(); String value = ex.value(); @@ -386,9 +385,15 @@ public boolean isHidden() { @Override public String getExample() { return apiParam.example(); - }; + } - public Example getExamples() { return apiParam.examples();}; + ; + + public Example getExamples() { + return apiParam.examples(); + } + + ; } /** @@ -460,8 +465,10 @@ public boolean isHidden() { @Override public String getExample() { return apiParam.example(); - }; + } - public Example getExamples() { return apiParam.examples();}; + public Example getExamples() { + return apiParam.examples(); + } } } From feedcd547f8816dfc7b0e8a2dcb29382cc3ce281 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 16 Oct 2015 18:16:02 -0700 Subject: [PATCH 5/7] removed unused call --- .../src/main/java/io/swagger/annotations/Example.java | 8 -------- 1 file changed, 8 deletions(-) diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java index ebe9003d98..0cd5dcae61 100644 --- a/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java +++ b/modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java @@ -29,14 +29,6 @@ @Target(ElementType.ANNOTATION_TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface Example { - - /** - * An option name for these examples. - * - * @return an option name for these examples - will be prefixed with "x-" - */ - String name() default ""; - /** * The examples properties. * From 5031bd48fb678c0b160875b2966e49cfcb283ae8 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Sun, 18 Oct 2015 21:30:32 -0700 Subject: [PATCH 6/7] updated response value, toString/hashCode --- .../java/io/swagger/SimpleScannerTest.java | 4 +- .../AbstractSerializableParameter.java | 171 ++++++------------ 2 files changed, 58 insertions(+), 117 deletions(-) diff --git a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java index 3f3a372c18..1b689fd7b0 100644 --- a/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java +++ b/modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java @@ -547,7 +547,7 @@ public void scanClassWithExampleQuery() { Parameter param = swagger.getPaths().get("/external/info").getGet().getParameters().get(0); QueryParameter bp = (QueryParameter) param; assertNotNull(bp.getExample()); - String value = bp.getExample(); + Object value = bp.getExample(); assertEquals("a,b,c", value); } @@ -557,7 +557,7 @@ public void scanClassWithImplicitExampleQuery() { Parameter param = swagger.getPaths().get("/external/info2").getGet().getParameters().get(0); QueryParameter bp = (QueryParameter) param; assertNotNull(bp.getExample()); - String value = bp.getExample(); + Object value = bp.getExample(); assertEquals("77", value); } } diff --git a/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java b/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java index 3df0d1ab87..14d1bd87c5 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/parameters/AbstractSerializableParameter.java @@ -225,10 +225,25 @@ public void setMinItems(Integer minItems) { } @JsonProperty("x-example") - public String getExample() { + public Object getExample() { + if (example == null) { + return null; + } + try { + if (BaseIntegerProperty.TYPE.equals(type)) { + return Long.valueOf(example); + } else if (DecimalProperty.TYPE.equals(type)) { + return Double.valueOf(example); + } else if (BooleanProperty.TYPE.equals(type)) { + if ("true".equalsIgnoreCase(example) || "false".equalsIgnoreCase(defaultValue)) { + return Boolean.valueOf(example); + } + } + } catch (NumberFormatException e) { + LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", defaultValue, type), e); + } return example; } - public void setExample(String example) { this.example = example; } @@ -241,124 +256,50 @@ private T castThis() { } @Override - public int hashCode() { - final int prime = 31; - int result = super.hashCode(); - result = prime * result + ((_enum == null) ? 0 : _enum.hashCode()); - result = prime * result - + ((collectionFormat == null) ? 0 : collectionFormat.hashCode()); - result = prime * result - + ((defaultValue == null) ? 0 : defaultValue.hashCode()); - result = prime * result - + ((exclusiveMaximum == null) ? 0 : exclusiveMaximum.hashCode()); - result = prime * result - + ((exclusiveMinimum == null) ? 0 : exclusiveMinimum.hashCode()); - result = prime * result + ((format == null) ? 0 : format.hashCode()); - result = prime * result + ((items == null) ? 0 : items.hashCode()); - result = prime * result + ((maximum == null) ? 0 : maximum.hashCode()); - result = prime * result + ((minimum == null) ? 0 : minimum.hashCode()); - result = prime * result + ((type == null) ? 0 : type.hashCode()); - result = prime * result + ((maxItems == null) ? 0 : maxItems.hashCode()); - result = prime * result + ((minItems == null) ? 0 : minItems.hashCode()); - return result; - } + public boolean equals(Object o) { + if (this == o) return true; + if (!(o instanceof AbstractSerializableParameter)) return false; + if (!super.equals(o)) return false; - @Override - public boolean equals(Object obj) { - if (this == obj) { - return true; - } - if (!super.equals(obj)) { - return false; - } - if (getClass() != obj.getClass()) { - return false; - } - AbstractSerializableParameter other = (AbstractSerializableParameter) obj; - if (_enum == null) { - if (other._enum != null) { - return false; - } - } else if (!_enum.equals(other._enum)) { - return false; - } - if (collectionFormat == null) { - if (other.collectionFormat != null) { - return false; - } - } else if (!collectionFormat.equals(other.collectionFormat)) { - return false; - } - if (defaultValue == null) { - if (other.defaultValue != null) { - return false; - } - } else if (!defaultValue.equals(other.defaultValue)) { - return false; - } - if (exclusiveMaximum == null) { - if (other.exclusiveMaximum != null) { - return false; - } - } else if (!exclusiveMaximum.equals(other.exclusiveMaximum)) { - return false; - } - if (exclusiveMinimum == null) { - if (other.exclusiveMinimum != null) { - return false; - } - } else if (!exclusiveMinimum.equals(other.exclusiveMinimum)) { + AbstractSerializableParameter that = (AbstractSerializableParameter) o; + + if (getType() != null ? !getType().equals(that.getType()) : that.getType() != null) return false; + if (getFormat() != null ? !getFormat().equals(that.getFormat()) : that.getFormat() != null) return false; + if (getCollectionFormat() != null ? !getCollectionFormat().equals(that.getCollectionFormat()) : that.getCollectionFormat() != null) return false; - } - if (format == null) { - if (other.format != null) { - return false; - } - } else if (!format.equals(other.format)) { + if (getItems() != null ? !getItems().equals(that.getItems()) : that.getItems() != null) return false; + if (_enum != null ? !_enum.equals(that._enum) : that._enum != null) return false; + if (exclusiveMaximum != null ? !exclusiveMaximum.equals(that.exclusiveMaximum) : that.exclusiveMaximum != null) return false; - } - if (items == null) { - if (other.items != null) { - return false; - } - } else if (!items.equals(other.items)) { + if (getMaximum() != null ? !getMaximum().equals(that.getMaximum()) : that.getMaximum() != null) return false; + if (exclusiveMinimum != null ? !exclusiveMinimum.equals(that.exclusiveMinimum) : that.exclusiveMinimum != null) return false; - } - if (maximum == null) { - if (other.maximum != null) { - return false; - } - } else if (!maximum.equals(other.maximum)) { + if (getMinimum() != null ? !getMinimum().equals(that.getMinimum()) : that.getMinimum() != null) return false; + if (getExample() != null ? !getExample().equals(that.getExample()) : that.getExample() != null) return false; + if (getMaxItems() != null ? !getMaxItems().equals(that.getMaxItems()) : that.getMaxItems() != null) return false; - } - if (minimum == null) { - if (other.minimum != null) { - return false; - } - } else if (!minimum.equals(other.minimum)) { + if (getMinItems() != null ? !getMinItems().equals(that.getMinItems()) : that.getMinItems() != null) return false; - } - if (type == null) { - if (other.type != null) { - return false; - } - } else if (!type.equals(other.type)) { - return false; - } - if (maxItems == null) { - if (other.maxItems != null) { - return false; - } - } else if (!maxItems.equals(other.maxItems)) { - return false; - } - if (minItems == null) { - if (other.minItems != null) { - return false; - } - } else if (!minItems.equals(other.minItems)) { - return false; - } - return true; + return !(getDefaultValue() != null ? !getDefaultValue().equals(that.getDefaultValue()) : that.getDefaultValue() != null); + + } + + @Override + public int hashCode() { + int result = super.hashCode(); + result = 31 * result + (getType() != null ? getType().hashCode() : 0); + result = 31 * result + (getFormat() != null ? getFormat().hashCode() : 0); + result = 31 * result + (getCollectionFormat() != null ? getCollectionFormat().hashCode() : 0); + result = 31 * result + (getItems() != null ? getItems().hashCode() : 0); + result = 31 * result + (_enum != null ? _enum.hashCode() : 0); + result = 31 * result + (exclusiveMaximum != null ? exclusiveMaximum.hashCode() : 0); + result = 31 * result + (getMaximum() != null ? getMaximum().hashCode() : 0); + result = 31 * result + (exclusiveMinimum != null ? exclusiveMinimum.hashCode() : 0); + result = 31 * result + (getMinimum() != null ? getMinimum().hashCode() : 0); + result = 31 * result + (getExample() != null ? getExample().hashCode() : 0); + result = 31 * result + (getMaxItems() != null ? getMaxItems().hashCode() : 0); + result = 31 * result + (getMinItems() != null ? getMinItems().hashCode() : 0); + result = 31 * result + (getDefaultValue() != null ? getDefaultValue().hashCode() : 0); + return result; } } From da61c09283d62e156b39e04da40357a8d46f86ad Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Mon, 19 Oct 2015 14:25:54 -0700 Subject: [PATCH 7/7] added title per #1470 --- .../main/java/io/swagger/models/AbstractModel.java | 11 +++++++++++ .../src/main/java/io/swagger/models/Model.java | 4 ++++ .../src/main/java/io/swagger/models/RefModel.java | 13 +++++++++++++ 3 files changed, 28 insertions(+) diff --git a/modules/swagger-models/src/main/java/io/swagger/models/AbstractModel.java b/modules/swagger-models/src/main/java/io/swagger/models/AbstractModel.java index 9e156d2ec2..19d92de171 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/AbstractModel.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/AbstractModel.java @@ -10,6 +10,7 @@ public abstract class AbstractModel implements Model { private ExternalDocs externalDocs; private String reference; + private String title; private final Map vendorExtensions = new HashMap(); @Override @@ -21,6 +22,16 @@ public void setExternalDocs(ExternalDocs value) { externalDocs = value; } + @Override + public String getTitle() { + return title; + } + + @Override + public void setTitle(String title) { + this.title = title; + } + @JsonAnyGetter public Map getVendorExtensions() { return vendorExtensions; diff --git a/modules/swagger-models/src/main/java/io/swagger/models/Model.java b/modules/swagger-models/src/main/java/io/swagger/models/Model.java index cfcc5dabd7..75eef7cfa1 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/Model.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/Model.java @@ -5,6 +5,10 @@ import java.util.Map; public interface Model { + String getTitle(); + + void setTitle(String title); + String getDescription(); void setDescription(String description); diff --git a/modules/swagger-models/src/main/java/io/swagger/models/RefModel.java b/modules/swagger-models/src/main/java/io/swagger/models/RefModel.java index c09118db6c..7afb19fb25 100644 --- a/modules/swagger-models/src/main/java/io/swagger/models/RefModel.java +++ b/modules/swagger-models/src/main/java/io/swagger/models/RefModel.java @@ -14,6 +14,7 @@ public class RefModel implements Model { private ExternalDocs externalDocs; private Map properties; private Object example; + private String title; public RefModel() { } @@ -27,6 +28,18 @@ public RefModel asDefault(String ref) { return this; } + // not allowed in a $ref + @JsonIgnore + @Override + public String getTitle() { + return title; + } + + @Override + public void setTitle(String title) { + this.title = title; + } + // not allowed in a $ref @JsonIgnore public String getDescription() {