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

Posted 星朝

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了springBoot 整合 swagger 展示返回对象的嵌套属性文档注释相关的知识,希望对你有一定的参考价值。

spring boot 处理 swagger 嵌套数据展示

在开发的过程中,我们会常常使用swagger做我们的在线文档.
我们会在对象的属性上使用@ApiModelProperty 等api注解,但是遇到对象嵌套的时候,如何返回一个嵌套的json文档就需要我们做一些简单的处理

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Data
@Slf4j
@Builder
@ApiModel(value = "统一数据返回对象", description = "所有数据经此包装")
public class WebResult implements Serializable {

public static final String REQUEST_STATUS_ERROR = "error";

public static final String REQUEST_STATUS_SUCCESS = "success";

private static final long serialVersionUID = 1L;

/**
* 状态码
*/
@ApiModelProperty(required = true, value = "返回状态码", dataType = "int", example = "200", position = 0)
private int code;

/**
* 返回数据
*/
@ApiModelProperty(required = true, value = "返回数据", dataType = "string", example = "data", position = 1)
private Object data;

/**
* msg信息
*/
@ApiModelProperty(required = true, value = "返回message 信息", dataType = "string", example = "success", position = 2)
private String message;

}

在设置统一返回时,如果仅仅把数据封装在Result对象的属性里, swagger并不会展示data内部的数据

创建一个对象,加入我们的Result中,启动swagger,查看接口的文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@ApiModel(value = "Person对象")
public class Person {

@ApiModelProperty("索引id")
private Long id;

@ApiModelProperty(value = "用户姓名")
private String name;

@ApiModelProperty(value = "密码")
private String pwd;

@ApiModelProperty(value = "备注")
private String remark;

}

控制器

1
2
3
4
5
6
7
8
9
@ApiOperation(value = "获取person json返回值", notes = "该操作不会展示嵌套的数据注释")
@PostMapping("/person")
public WebResult findPerson() {
return WebResult.builder()
.code(200)
.message(REQUEST_STATUS_SUCCESS)
.data(new Person(1, "myName", "123456", "测试数据"))
.build();
}

我们发现最后自动生成的文档里并没有我们需要的内嵌信息

技术图片

为了展示内嵌的数据对象进行泛型修改

使用泛型指定的swagger,可以展示data的数据内部文档注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
@Data
@Builder
@ApiModel(value = "统一数据返回对象",
description = "所有数据经此包装,使用了泛型,可展示泛型内的数据文档注释")
public class WebProResult<T> implements Serializable {

public static final String REQUEST_STATUS_ERROR = "error";
public static final String REQUEST_STATUS_SUCCESS = "success";
private static final long serialVersionUID = 1L;
/**
* 状态码
*/
@ApiModelProperty(required = true,
value = "返回状态码",
dataType = "int",
example = "200", position = 0)
private int code;
/**
* 返回数据
*/
@ApiModelProperty(required = true,
value = "返回数据",
dataType = "string",
example = "data", position = 1)
private T data;
/**
* msg信息
*/
@ApiModelProperty(required = true,
value = "返回message 信息",
dataType = "string",
example = "success", position = 2)
private String message;

}

控制器的代码

这里都用到了 lombok 的@Builder进行创建对象

注意加上泛型之后的写法

1
2
3
4
5
6
7
8
9
10
@ApiOperation(value = "获取person json返回值", 
notes = "通过泛型指定,我们告诉了swagger属性内的对象是什么")
@PostMapping("/person/pro")
public WebProResult<Person> findPersonPro() {
return WebProResult.<Person>builder()
.code(200)
.message(REQUEST_STATUS_SUCCESS)
.data(new Person(1, "myName", "123456", "测试数据"))
.build();
}

最后我们发现可以通过swagger得到所有加过的文档注释

在接口的文档注释中,直接可以点开内部的信息

技术图片

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@Data
@Builder
@ApiModel(value = "分页数据", description = "分页数据统一返回对象")
public class PageVo<T> {

@ApiModelProperty(value = "列表数据",
dataType = "String",
name = "values", example = "")
private List<T> values;

/**
* 分页
*/
@ApiModelProperty(value = "第几页",
dataType = "int",
name = "page", example = "1")
private int page;

/**
* 分页值
*/
@ApiModelProperty(value = "每页多少条",
dataType = "int",
name = "size", example = "10")
private int size;

/**
* 一共查询了多少条数据
*/
@ApiModelProperty(value = "一共查询了多少条数据",
dataType = "long",
name = "total",
notes = "不需要传输 仅返回时展示使用")
private long total;


}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@ApiOperation(value = "获取person json返回值", notes = "通过泛型指定,多层嵌套也可展示")
@PostMapping("/person/page")
public WebProResult<PageVo<Person>> findPersonPage() {

Person person = new Person(1, "myName", "123456", "测试数据");

PageVo<Person> pageVo = PageVo.<Person>builder()
.page(1)
.size(10)
.total(20)
.values(Collections.singletonList(person))
.build();

return WebProResult.<PageVo<Person>>builder()
.code(200)
.message(REQUEST_STATUS_SUCCESS)
.data(pageVo)
.build();
}

swagger 多层嵌套返回了每一个内部对象的文档注释

依此点开,可以看到内部信息

技术图片

github Demo

源码地址

https://github.com/1119264845/blog-examples

原文地址: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%E5%A5%97%E5%B1%9E%E6%80%A7%E6%96%87%E6%A1%A3%E6%B3%A8%E9%87%8A/#spring-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



























































































































































































































































































































以上是关于springBoot 整合 swagger 展示返回对象的嵌套属性文档注释的主要内容,如果未能解决你的问题,请参考以下文章

SpringBoot与Swagger整合

SpringBoot整合Springfox-Swagger2

SpringBoot整合Swagger2

SpringBoot学习—— springboot快速整合swagger文档

SpringBoot-整合Swagger2

SpringBoot整合Swagger2