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;
@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;
@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
