springBoot整合swagger展示返回对象的嵌套属性文档注释

spring boot 处理 swagger 嵌套数据展⽰

在开发的过程中,我们会常常使⽤做我们的在线⽂档.

我们会在对象的属性上使⽤@ApiModelProperty 等api注解,但是遇到对象嵌套的时候,如何返回⼀个嵌套的json⽂档就需要我们做⼀些简单的处理

如果只在对象某个属性上使⽤ @ApiModelProperty 并不会起作⽤

1@Data2@Slf4j3@Builder

4@ApiModel(value = \"统⼀数据返回对象\所有数据经此包装\")5public class WebResult implements Serializable {6

7 public static final String REQUEST_STATUS_ERROR = \"error\";8

9 public static final String REQUEST_STATUS_SUCCESS = \"success\";10

11 private static final long serialVersionUID = 1L;12 13 /**

14 * 状态码15 */

16 @ApiModelProperty(required = true, value = \"返回状态码\17 private int code;18 19 /**

20 * 返回数据21 */

22 @ApiModelProperty(required = true, value = \"返回数据\23 private Object data;24 25 /**

26 * msg信息27 */

28 @ApiModelProperty(required = true, value = \"返回message 信息\29 private String message;3031}

在设置统⼀返回时,如果仅仅把数据封装在Result对象的属性⾥, swagger并不会展⽰data内部的数据创建⼀个对象,加⼊我们的Result中,启动swagger,查看接⼝的⽂档

1@ApiModel(value = \"Person对象\")2public class Person {3

4 @ApiModelProperty(\"索引id\")5 private Long id;6

7 @ApiModelProperty(value = \"⽤户姓名\")8 private String name;9

10 @ApiModelProperty(value = \"密码\")11 private String pwd;12

13 @ApiModelProperty(value = \"备注\")14 private String remark;15 16}

控制器

1@ApiOperation(value = \"获取person json返回值\该操作不会展⽰嵌套的数据注释\")2 @PostMapping(\"/person\")

3 public WebResult findPerson() {4 return WebResult.builder()5 .code(200)

6 .message(REQUEST_STATUS_SUCCESS)

7 .data(new Person(1, \"myName\测试数据\"))8 .build();9 }

我们发现最后⾃动⽣成的⽂档⾥并没有我们需要的内嵌信息

为了展⽰内嵌的数据对象进⾏泛型修改

使⽤泛型指定的swagger,可以展⽰data的数据内部⽂档注释

1@Data2@Builder

3@ApiModel(value = \"统⼀数据返回对象\

4 description = \"所有数据经此包装,使⽤了泛型,可展⽰泛型内的数据⽂档注释\")5public class WebProResult implements Serializable {6

7 public static final String REQUEST_STATUS_ERROR = \"error\";

8 public static final String REQUEST_STATUS_SUCCESS = \"success\";9 private static final long serialVersionUID = 1L;10 /**

11 * 状态码12 */

13 @ApiModelProperty(required = true, 14 value = \"返回状态码\15 dataType = \"int\

16 example = \"200\17 private int code;18 /**

19 * 返回数据20 */

21 @ApiModelProperty(required = true, 22 value = \"返回数据\23 dataType = \"string\

24 example = \"data\25 private T data;26 /**

27 * msg信息28 */

29 @ApiModelProperty(required = true,

30 value = \"返回message 信息\31 dataType = \"string\

32 example = \"success\33 private String message;34

35}

控制器的代码

这⾥都⽤到了 lombok 的@Builder进⾏创建对象注意加上泛型之后的写法

1@ApiOperation(value = \"获取person json返回值\

2 notes = \"通过泛型指定,我们告诉了swagger属性内的对象是什么\")3@PostMapping(\"/person/pro\")

4public WebProResult findPersonPro() {5 return WebProResult.builder()6 .code(200)

7 .message(REQUEST_STATUS_SUCCESS)

8 .data(new Person(1, \"myName\测试数据\"))9 .build();10}

最后我们发现可以通过swagger得到所有加过的⽂档注释在接⼝的⽂档注释中,直接可以点开内部的信息

通过泛型,即使是多个对象互相嵌套也可展⽰

接⼝不单只获取⼀个对象,还有分页信息,添加⼀个拥有泛型的分页对象

1@Data2@Builder

3@ApiModel(value = \"分页数据\分页数据统⼀返回对象\")4public class PageVo {5

6 @ApiModelProperty(value = \"列表数据\7 dataType = \"String\

8 name = \"values\9 private List values;10

11 /**12 * 分页13 */

14 @ApiModelProperty(value = \"第⼏页\15 dataType = \"int\

16 name = \"page\17 private int page;18 19 /**

20 * 分页值21 */

22 @ApiModelProperty(value = \"每页多少条\23 dataType = \"int\

24 name = \"size\25 private int size;26 27 /**

28 * ⼀共查询了多少条数据29 */

30 @ApiModelProperty(value = \"⼀共查询了多少条数据\31 dataType = \"long\32 name = \"total\

33 notes = \"不需要传输 仅返回时展⽰使⽤\")34 private long total;353637}

控制器返回封装的分页信息,仍通过Result多层嵌套返回json

1@ApiOperation(value = \"获取person json返回值\通过泛型指定,多层嵌套也可展⽰\")2@PostMapping(\"/person/page\")

3public WebProResult> findPersonPage() {4

5 Person person = new Person(1, \"myName\测试数据\");6

7 PageVo pageVo = PageVo.builder()8 .page(1)9 .size(10)10 .total(20)

11 .values(Collections.singletonList(person))12 .build();13

14 return WebProResult.>builder()15 .code(200)

16 .message(REQUEST_STATUS_SUCCESS)17 .data(pageVo)18 .build();19}

swagger 多层嵌套返回了每⼀个内部对象的⽂档注释依此点开,可以看到内部信息

github Demo

源码地址

原⽂地

址:http://www.elfop.com/2019/07/24/springBoot%E6%95%B4%E5%90%88swagger%E5%B1%95%E7%A4%BA%E8%BF%94%E5%9B%9E%E5%AF%B9%E8%B1%A1%E7%9A%84%E5%B5%8C%boot-%E5%A4%84%E7%90%86-swagger-%E5%B5%8C%E5%A5%97%E6%95%B0%E6%8D%AE%E5%B1%95%E7%A4%BA