由于spring boot能夠快速開發(fā)、便捷部署等特性，相信有很大一部分spring boot的用戶會用來構(gòu)建restful api。而我們構(gòu)建restful api的目的通常都是由于多終端的原因，這些終端會共用很多底層業(yè)務(wù)邏輯，因此我們會抽象出這樣一層來同時服務(wù)于多個移動端或者web前端。
swagger inspector：測試api和生成openapi的開發(fā)工具。swagger inspector的建立是為了解決開發(fā)者的三個主要目標(biāo)。
- 執(zhí)行簡單的api測試
- 生成openapi文檔
- 探索新的api功能
下面來具體介紹，如果在spring boot中使用swagger2。
添加swagger2依賴
在pom.xml中加入swagger2的依賴
|
1
2
3
4
5
6
7
8
9
10
11
|
<!-- swagger api--> <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.2.2</version> </dependency> <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.2.2</version> </dependency> |
創(chuàng)建swagger2配置類
在hrabbitadminapplication.java子包下創(chuàng)建swagger2的配置類swagger2。
通過@configuration注解，讓spring來加載該類配置。再通過@enableswagger2注解來啟用swagger2。
再通過createrestapi函數(shù)創(chuàng)建docket的bean之后，apiinfo()用來創(chuàng)建該api的基本信息（這些基本信息會展現(xiàn)在文檔頁面中）。select()函數(shù)返回一個apiselectorbuilder實例用來控制哪些接口暴露給swagger來展現(xiàn)，包含注解的方式來確定要顯示的接口，當(dāng)然也可以通過包掃描的方式來確定要顯示的包的接口。
|
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
|
/** * 配置swagger * * @auther: hrabbit * @date: 2018-12-17 6:43 pm * @description: */@configuration@enableswagger2public class swaggerconfig { @bean public docket createrestapi() { return new docket(documentationtype.swagger_2) .apiinfo(apiinfo()) .select() .apis(requesthandlerselectors.withmethodannotation(apioperation.class)) //這里采用包含注解的方式來確定要顯示的接口 //.apis(requesthandlerselectors.basepackage("com.hrabbit.admin.modual.system.controller")) //這里采用包掃描的方式來確定要顯示的接口 .paths(pathselectors.any()) .build(); } private apiinfo apiinfo() { return new apiinfobuilder() .title("hrabbit-admin doc") .description("guns api文檔") .termsofserviceurl("https://gitee.com/hrabbit/hrabbit-admin") .contact("hrabbit") .version("1.0") .build(); }} |
添加文檔內(nèi)容
我們通過@api說明controller，@apioperation注解來給api增加說明、通過@apiimplicitparams、@apiimplicitparam注解來給參數(shù)增加說明。
|
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
/** * 系統(tǒng)用戶 * * @auther: hrabbit * @date: 2018-12-17 6:21 pm * @description: */@controller@requestmapping("user")@api(value = "系統(tǒng)用戶")public class sysusercontroller { @autowired private sysuserservice sysuserservice; /** * 根據(jù)id獲取用戶信息 * * @return */ @requestmapping("/",method = requestmethod.get) @responsebody @apioperation(value = "進入到主頁") public object index() { return sysuserservice.selectbyid(1l); } /** * 創(chuàng)建用戶信息 * * @param user * @return */ @apioperation(value = "創(chuàng)建用戶", notes = "根據(jù)sysuser對象創(chuàng)建用戶") @apiimplicitparam(name = "user", value = "用戶詳細(xì)實體user", required = true, datatype = "sysuser") @requestmapping(value = "", method = requestmethod.post) public string postuser(@requestbody sysuser user) { return "success"; } /** * 修改用戶信息 * * @param id * @param user * @return */ @apioperation(value = "更新用戶詳細(xì)信息", notes = "根據(jù)id更新系統(tǒng)用戶") @apiimplicitparams({ @apiimplicitparam(name = "id", value = "用戶id", required = true, datatype = "long"), @apiimplicitparam(name = "user", value = "用戶詳細(xì)實體sysuser", required = true, datatype = "sysuser") }) @requestmapping(value = "/{id}", method = requestmethod.put) public string putuser(@pathvariable long id, @requestbody sysuser user) { return "success"; }} |
完成上述代碼添加上，啟動spring boot程序，訪問：http://localhost:8080/swagger-ui.html
。就能看到前文所展示的restful api的頁面。我們可以再點開具體的api請求，以post類型的/user請求為例，可找到上述代碼中我們配置的notes信息以及參數(shù)user的描述信息，如下圖所示。
api文檔訪問與調(diào)試
在上圖請求的頁面中，我們看到user的value是個輸入框？是的，swagger除了查看接口功能外，還提供了調(diào)試測試功能，我們可以點擊上圖中右側(cè)的model schema（黃色區(qū)域：它指明了user的數(shù)據(jù)結(jié)構(gòu)），此時value中就有了user對象的模板，我們只需要稍適修改，點擊下方“try it out！”按鈕，即可完成了一次請求調(diào)用！
本篇文章，一些文字內(nèi)容借鑒了程序猿dd的swagger內(nèi)容，該系列文章內(nèi)容主要以如何搭建一個完整的后臺spirng boot cli為主，其他的基礎(chǔ)信息可以參考其他博主內(nèi)容！
碼云地址：https://gitee.com/hrabbit/hrabbit-admin
以上就是本文的全部內(nèi)容，希望對大家的學(xué)習(xí)有所幫助，也希望大家多多支持服務(wù)器之家。
原文鏈接：https://www.jianshu.com/p/8cf56d8e2793
