Skip to content

Commit 2867cbb

Browse files
fehguyfehguy
committed
added example value support for post params, #1500 
1 parent f4764e5 commit 2867cbb

File tree

7 files changed

+180
-25
lines changed

7 files changed

+180
-25
lines changed

‎modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,4 +92,17 @@
9292
* Hides the parameter from the list of parameters.
9393
*/
9494
boolean hidden() default false;
95+
96+
/**
97+
* a single example for non-body type parameters
98+
*
99+
* @return
100+
*/
101+
String example() default "";
102+
103+
/**
104+
* Examples for the parameter. Applies only to BodyParameters
105+
* @return
106+
*/
107+
Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
95108
}

‎modules/swagger-annotations/src/main/java/io/swagger/annotations/Example.java‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/**
2+
* Copyright 2015 SmartBear Software
3+
* <p>
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* <p>
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
* <p>
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.swagger.annotations;
18+
19+
import java.lang.annotation.ElementType;
20+
import java.lang.annotation.Retention;
21+
import java.lang.annotation.RetentionPolicy;
22+
import java.lang.annotation.Target;
23+
24+
/**
25+
* An optionally named list of example properties.
26+
*
27+
* @since 1.5.4
28+
*/
29+
@Target(ElementType.ANNOTATION_TYPE)
30+
@Retention(RetentionPolicy.RUNTIME)
31+
public @interface Example {
32+
33+
/**
34+
* An option name for these examples.
35+
*
36+
* @return an option name for these examples - will be prefixed with "x-"
37+
*/
38+
String name() default "";
39+
40+
/**
41+
* The examples properties.
42+
*
43+
* @return the actual extension properties
44+
* @see ExampleProperty
45+
*/
46+
ExampleProperty[] value();
47+
}

‎modules/swagger-annotations/src/main/java/io/swagger/annotations/ExampleProperty.java‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/**
2+
* Copyright 2015 SmartBear Software
3+
* <p>
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* <p>
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
* <p>
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.swagger.annotations;
18+
19+
import java.lang.annotation.ElementType;
20+
import java.lang.annotation.Retention;
21+
import java.lang.annotation.RetentionPolicy;
22+
import java.lang.annotation.Target;
23+
24+
/**
25+
* A mediaType/value property within a Swagger example
26+
*
27+
* @see Example
28+
* @since 1.5.4
29+
*/
30+
@Target(ElementType.ANNOTATION_TYPE)
31+
@Retention(RetentionPolicy.RUNTIME)
32+
public @interface ExampleProperty {
33+
34+
/**
35+
* The name of the property.
36+
*
37+
* @return the name of the property
38+
*/
39+
String mediaType() default "default";
40+
41+
/**
42+
* The value of the example.
43+
*
44+
* @return the value of the example
45+
*/
46+
String value();
47+
}

‎modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
import io.swagger.annotations.ApiImplicitParam;
44
import io.swagger.annotations.ApiParam;
5+
import io.swagger.annotations.Example;
6+
import io.swagger.annotations.ExampleProperty;
57
import io.swagger.converter.ModelConverters;
68
import io.swagger.models.Model;
79
import io.swagger.models.Swagger;
@@ -103,6 +105,23 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
103105
// must be a body param
104106
BodyParameter bp = new BodyParameter();
105107

108+
if(helper.getApiParam() != null) {
109+
ParamWrapper<?> pw = helper.getApiParam();
110+
111+
if(pw instanceof ApiParamWrapper) {
112+
ApiParamWrapper apiParam = (ApiParamWrapper) pw;
113+
Example example = apiParam.getExample();
114+
if(example != null && example.value() != null) {
115+
for (ExampleProperty ex : example.value()) {
116+
String mediaType = ex.mediaType();
117+
String value = ex.value();
118+
if (!mediaType.isEmpty() && !value.isEmpty()) {
119+
bp.example(mediaType.trim(), value.trim());
120+
}
121+
}
122+
}
123+
}
124+
}
106125
bp.setRequired(param.isRequired());
107126
bp.setName(StringUtils.isNotEmpty(param.getName()) ? param.getName() : "body");
108127

@@ -341,6 +360,8 @@ public ApiParam getAnnotation() {
341360
public boolean isHidden() {
342361
return apiParam.hidden();
343362
}
363+
364+
public Example getExample() { return apiParam.examples();};
344365
}
345366

346367
/**

‎modules/swagger-jaxrs/src/test/java/io/swagger/SimpleScannerTest.java‎

Lines changed: 8 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -28,32 +28,9 @@
2828
import io.swagger.models.properties.Property;
2929
import io.swagger.models.properties.RefProperty;
3030
import io.swagger.models.properties.StringProperty;
31-
import io.swagger.resources.HiddenResource;
32-
import io.swagger.resources.Resource1041;
33-
import io.swagger.resources.Resource1073;
34-
import io.swagger.resources.Resource1085;
35-
import io.swagger.resources.Resource653;
36-
import io.swagger.resources.Resource841;
37-
import io.swagger.resources.Resource877;
38-
import io.swagger.resources.Resource937;
39-
import io.swagger.resources.ResourceWithApiOperationCode;
40-
import io.swagger.resources.ResourceWithApiResponseResponseContainer;
41-
import io.swagger.resources.ResourceWithBodyParams;
42-
import io.swagger.resources.ResourceWithEmptyModel;
43-
import io.swagger.resources.ResourceWithEnums;
44-
import io.swagger.resources.ResourceWithInnerClass;
45-
import io.swagger.resources.ResourceWithMapReturnValue;
46-
import io.swagger.resources.ResourceWithRanges;
47-
import io.swagger.resources.ResourceWithResponse;
48-
import io.swagger.resources.ResourceWithResponseHeaders;
49-
import io.swagger.resources.ResourceWithTypedResponses;
50-
import io.swagger.resources.ResourceWithVoidReturns;
51-
import io.swagger.resources.SimpleResource;
52-
import io.swagger.resources.SimpleResourceWithoutAnnotations;
53-
import io.swagger.resources.SimpleSelfReferencingSubResource;
54-
import io.swagger.resources.TaggedResource;
55-
import io.swagger.resources.NicknamedOperation;
31+
import io.swagger.resources.*;
5632

33+
import io.swagger.util.Json;
5734
import org.testng.annotations.Test;
5835

5936
import java.util.ArrayList;
@@ -541,4 +518,10 @@ public void scanResourceWithApiOperationNickname() {
541518

542519
assertEquals(op.getOperationId(), "getMyNicknameTest");
543520
}
521+
522+
@Test(description = "scan a resource with custom operation nickname")
523+
public void scanClassWithExamplePost() {
524+
Swagger swagger = getSwagger(ClassWithExamplePost.class);
525+
Json.prettyPrint(swagger);
526+
}
544527
}

‎modules/swagger-jaxrs/src/test/java/io/swagger/resources/ClassWithExamplePost.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
package io.swagger.resources;
2+
3+
import io.swagger.annotations.*;
4+
5+
import javax.ws.rs.POST;
6+
import javax.ws.rs.Path;
7+
import java.util.ArrayList;
8+
9+
@Api("/external/info/")
10+
@Path("external/info/")
11+
public class ClassWithExamplePost {
12+
@ApiOperation(value = "test.")
13+
@POST
14+
public void postTest(@ApiParam(value = "test",
15+
examples = @Example(value = {@ExampleProperty(mediaType="fun", value="bar")})) ArrayList<String> tenantId) {
16+
return;
17+
}
18+
}

‎modules/swagger-models/src/main/java/io/swagger/models/parameters/BodyParameter.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
package io.swagger.models.parameters;
22

3+
import com.fasterxml.jackson.annotation.JsonProperty;
34
import io.swagger.models.Model;
45

6+
import java.util.HashMap;
7+
import java.util.Map;
8+
59
public class BodyParameter extends AbstractParameter implements Parameter {
610
Model schema;
11+
Map<String, String> examples;
712

813
public BodyParameter() {
914
super.setIn("body");
@@ -14,6 +19,11 @@ public BodyParameter schema(Model schema) {
1419
return this;
1520
}
1621

22+
public BodyParameter example(String mediaType, String value) {
23+
this.addExample(mediaType, value);
24+
return this;
25+
}
26+
1727
public BodyParameter description(String description) {
1828
this.setDescription(description);
1929
return this;
@@ -32,6 +42,22 @@ public void setSchema(Model schema) {
3242
this.schema = schema;
3343
}
3444

45+
public void addExample(String mediaType, String value) {
46+
if(examples == null) {
47+
examples = new HashMap<String, String>();
48+
}
49+
examples.put(mediaType, value);
50+
}
51+
52+
@JsonProperty("x-examples")
53+
public Map<String, String> getExamples() {
54+
return examples;
55+
}
56+
57+
public void setExamples(Map<String, String> examples) {
58+
this.examples = examples;
59+
}
60+
3561
@Override
3662
public int hashCode() {
3763
final int prime = 31;

0 commit comments

Comments
 (0)