Skip to content

Commit 62c100f

Browse files
fehguyfehguy
committed
added example support for non-body params, implicits
1 parent 4a10385 commit 62c100f

File tree

6 files changed

+152
-9
lines changed

6 files changed

+152
-9
lines changed

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,4 +109,22 @@
109109
* Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
110110
*/
111111
String paramType() default "";
112+
113+
/**
114+
* a single example for non-body type parameters
115+
*
116+
* @since 1.5.4
117+
*
118+
* @return
119+
*/
120+
String example() default "";
121+
122+
/**
123+
* Examples for the parameter. Applies only to BodyParameters
124+
*
125+
* @since 1.5.4
126+
*
127+
* @return
128+
*/
129+
Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
112130
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,12 +96,17 @@
9696
/**
9797
* a single example for non-body type parameters
9898
*
99+
* @since 1.5.4
100+
*
99101
* @return
100102
*/
101103
String example() default "";
102104

103105
/**
104106
* Examples for the parameter. Applies only to BodyParameters
107+
*
108+
* @since 1.5.4
109+
*
105110
* @return
106111
*/
107112
Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));

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

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,12 +52,18 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
5252
if (StringUtils.isNotEmpty(param.getDescription())) {
5353
p.setDescription(param.getDescription());
5454
}
55+
if (StringUtils.isNotEmpty(param.getExample())) {
56+
p.setExample(param.getExample());
57+
}
5558
if (StringUtils.isNotEmpty(param.getAccess())) {
5659
p.setAccess(param.getAccess());
5760
}
5861
if (StringUtils.isNotEmpty(param.getDataType())) {
5962
p.setType(param.getDataType());
6063
}
64+
if (StringUtils.isNotEmpty(param.getExample())) {
65+
p.setType(param.getExample());
66+
}
6167
if (helper.getMinItems() != null) {
6268
p.setMinItems(helper.getMinItems());
6369
}
@@ -82,6 +88,7 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
8288
args.put(PropertyBuilder.PropertyId.MAXIMUM, p.getMaximum());
8389
p.setMaximum(null);
8490
args.put(PropertyBuilder.PropertyId.EXCLUSIVE_MAXIMUM, p.isExclusiveMaximum());
91+
args.put(PropertyBuilder.PropertyId.EXAMPLE, p.getExample());
8592
p.setExclusiveMaximum(null);
8693
Property items = PropertyBuilder.build(p.getType(), p.getFormat(), args);
8794
p.type(ArrayProperty.TYPE).format(null).items(items);
@@ -110,7 +117,20 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
110117

111118
if(pw instanceof ApiParamWrapper) {
112119
ApiParamWrapper apiParam = (ApiParamWrapper) pw;
113-
Example example = apiParam.getExample();
120+
Example example = apiParam.getExamples();
121+
if(example != null && example.value() != null) {
122+
for (ExampleProperty ex : example.value()) {
123+
String mediaType = ex.mediaType();
124+
String value = ex.value();
125+
if (!mediaType.isEmpty() && !value.isEmpty()) {
126+
bp.example(mediaType.trim(), value.trim());
127+
}
128+
}
129+
}
130+
}
131+
else if(pw instanceof ApiImplicitParamWrapper) {
132+
ApiImplicitParamWrapper apiParam = (ApiImplicitParamWrapper) pw;
133+
Example example = apiParam.getExamples();
114134
if(example != null && example.value() != null) {
115135
for (ExampleProperty ex : example.value()) {
116136
String mediaType = ex.mediaType();
@@ -198,6 +218,8 @@ public interface ParamWrapper<T extends Annotation> {
198218
T getAnnotation();
199219

200220
boolean isHidden();
221+
222+
String getExample();
201223
}
202224

203225
/**
@@ -361,7 +383,12 @@ public boolean isHidden() {
361383
return apiParam.hidden();
362384
}
363385

364-
public Example getExample() { return apiParam.examples();};
386+
@Override
387+
public String getExample() {
388+
return apiParam.example();
389+
};
390+
391+
public Example getExamples() { return apiParam.examples();};
365392
}
366393

367394
/**
@@ -429,5 +456,12 @@ public ApiImplicitParam getAnnotation() {
429456
public boolean isHidden() {
430457
return false;
431458
}
459+
460+
@Override
461+
public String getExample() {
462+
return apiParam.example();
463+
};
464+
465+
public Example getExamples() { return apiParam.examples();};
432466
}
433467
}

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

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -519,15 +519,45 @@ public void scanResourceWithApiOperationNickname() {
519519
assertEquals(op.getOperationId(), "getMyNicknameTest");
520520
}
521521

522-
@Test(description = "scan a resource with custom operation nickname")
522+
@Test(description = "scan a resource with operation post example")
523523
public void scanClassWithExamplePost() {
524524
Swagger swagger = getSwagger(ClassWithExamplePost.class);
525525
Parameter param = swagger.getPaths().get("/external/info").getPost().getParameters().get(0);
526-
Json.prettyPrint(param);
527526
BodyParameter bp = (BodyParameter) param;
528527
assertNotNull(bp.getExamples());
529528
assertTrue(bp.getExamples().size() == 1);
530-
String value = bp.getExamples().get("foo");
531-
assertEquals("bar", value);
529+
String value = bp.getExamples().get("application/json");
530+
assertEquals("[\"a\",\"b\"]", value);
531+
}
532+
533+
@Test(description = "scan a resource with operation implicit post example")
534+
public void scanClassWithImplicitExamplePost() {
535+
Swagger swagger = getSwagger(ClassWithExamplePost.class);
536+
Parameter param = swagger.getPaths().get("/external/info2").getPost().getParameters().get(0);
537+
BodyParameter bp = (BodyParameter) param;
538+
assertNotNull(bp.getExamples());
539+
assertTrue(bp.getExamples().size() == 1);
540+
String value = bp.getExamples().get("application/json");
541+
assertEquals("[\"a\",\"b\"]", value);
542+
}
543+
544+
@Test(description = "scan a resource with query param example")
545+
public void scanClassWithExampleQuery() {
546+
Swagger swagger = getSwagger(ClassWithExamplePost.class);
547+
Parameter param = swagger.getPaths().get("/external/info").getGet().getParameters().get(0);
548+
QueryParameter bp = (QueryParameter) param;
549+
assertNotNull(bp.getExample());
550+
String value = bp.getExample();
551+
assertEquals("a,b,c", value);
552+
}
553+
554+
@Test(description = "scan a resource with implicit operation query example")
555+
public void scanClassWithImplicitExampleQuery() {
556+
Swagger swagger = getSwagger(ClassWithExamplePost.class);
557+
Parameter param = swagger.getPaths().get("/external/info2").getGet().getParameters().get(0);
558+
QueryParameter bp = (QueryParameter) param;
559+
assertNotNull(bp.getExample());
560+
String value = bp.getExample();
561+
assertEquals("77", value);
532562
}
533563
}

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

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,57 @@
22

33
import io.swagger.annotations.*;
44

5+
import javax.ws.rs.GET;
56
import javax.ws.rs.POST;
67
import javax.ws.rs.Path;
8+
import javax.ws.rs.QueryParam;
79
import java.util.ArrayList;
810

911
@Api("/external/info/")
10-
@Path("external/info/")
1112
public class ClassWithExamplePost {
12-
@ApiOperation(value = "test.")
13+
@ApiOperation(value = "test")
1314
@POST
15+
@Path("external/info")
1416
public void postTest(@ApiParam(value = "test",
15-
examples = @Example(value = {@ExampleProperty(mediaType="foo", value="bar")})) ArrayList<String> tenantId) {
17+
examples = @Example(value = {
18+
@ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]")
19+
})) ArrayList<String> tenantId) {
20+
return;
21+
}
22+
23+
@ApiOperation(value = "test")
24+
@POST
25+
@Path("external/info2")
26+
@ApiImplicitParams({
27+
@ApiImplicitParam(
28+
paramType = "body",
29+
name = "myPody",
30+
dataType = "[Ljava.lang.String;",
31+
examples = @Example(value = {
32+
@ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]")}))
33+
})
34+
public void implicitPostTest() {
35+
return;
36+
}
37+
38+
@ApiOperation(value = "test")
39+
@GET
40+
@Path("external/info")
41+
public void queryExample(@ApiParam(value = "test",
42+
example = "a,b,c") @QueryParam("tenantId") ArrayList<String> tenantId) {
43+
return;
44+
}
45+
46+
@ApiOperation(value = "test")
47+
@GET
48+
@Path("external/info2")
49+
@ApiImplicitParams({
50+
@ApiImplicitParam(
51+
paramType = "query",
52+
name = "myId",
53+
dataType = "java.lang.Long",
54+
example = "77") })
55+
public void implicitQueryExample() {
1656
return;
1757
}
1858
}

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

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

33
import com.fasterxml.jackson.annotation.JsonIgnore;
4+
import com.fasterxml.jackson.annotation.JsonProperty;
45
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
56

67
import org.slf4j.Logger;
@@ -28,6 +29,7 @@ public abstract class AbstractSerializableParameter<T extends AbstractSerializab
2829
protected Double maximum;
2930
protected Boolean exclusiveMinimum;
3031
protected Double minimum;
32+
protected String example;
3133
private Integer maxItems;
3234
private Integer minItems;
3335

@@ -69,6 +71,11 @@ public T collectionFormat(String collectionFormat) {
6971
return castThis();
7072
}
7173

74+
public T example(String example) {
75+
this.setExample(example);
76+
return castThis();
77+
}
78+
7279
@JsonIgnore
7380
protected String getDefaultCollectionFormat() {
7481
return "csv";
@@ -217,6 +224,15 @@ public void setMinItems(Integer minItems) {
217224
this.minItems = minItems;
218225
}
219226

227+
@JsonProperty("x-example")
228+
public String getExample() {
229+
return example;
230+
}
231+
232+
public void setExample(String example) {
233+
this.example = example;
234+
}
235+
220236
@JsonIgnore
221237
private T castThis() {
222238
@SuppressWarnings("unchecked")

0 commit comments

Comments
 (0)