摘要：在項目開發(fā)中，往往期望做到前后端分離，也就是后端開發(fā)人員往往需要輸出大量的服務接口，接口的提供方無論是是java還是php等語言，往往會要花費一定的精力去寫接口文檔，比如a接口的地址、需要傳遞參數(shù)情況、返回值的json數(shù)據(jù)格式以及每一個字段說明、當然還要考慮http請求頭、請求內(nèi)容等信息。隨著項目的進度快速高速的迭代，后端輸出的接口往往會面臨修改、修復等問題，那也意味著接口文檔也要進行相應的調(diào)整。接口文檔的維護度以及可讀性就大大下降。
既然接口文檔需要花費精力去維護，還要適當?shù)倪M行面對面交流溝通，我們何不想一個辦法，第一：可以不用寫接口文檔；第二：前端與后端溝通接口問題的時候，后端是否可以提供一個url，在這個url中羅列出所有可以調(diào)用的服務接口，并在每個服務接口中羅列出參數(shù)的說明，返回值的說明，第三：后端接口如果能模擬調(diào)用就所有問題都解決了。本文我們重點講解一下sringboot中集成swagger2框架。
1.1. 添加swagger2依賴
在項目的pom.xml文件中增加如下的依賴。
|
1
2
3
4
5
6
7
8
9
10
|
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.7.0</version></dependency><dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.7.0</version></dependency> |
首先，我們需要建立一個啟動類，代碼如下：
|
1
2
3
4
5
6
|
@springbootapplicationpublic class application { public static void main(string[] args) { springapplication.run(application.class, args); }} |
然后在上述類的同級目錄中新建swagger2的配置類如下所示：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
@configuration@enableswagger2public class swagger2 { @bean public docket createrestapi() { return new docket(documentationtype.swagger_2) .apiinfo(apiinfo()) .select() .apis(requesthandlerselectors.basepackage("com.shareniu.web")) .paths(pathselectors.any()) .build(); } private apiinfo apiinfo() { return new apiinfobuilder() .title("跟著分享牛學習springboot源碼分析系列課程") .description("更多spring boot相關文章請關注分享牛的博客") .termsofserviceurl("http://www.shareniu.com/") .contact("牛牛") .license("copyright 2017-2018 分享牛") .version("1.0") .build(); }} |
@configuration制定了spring要加載這個類，@enableswagger2注解要開啟swagger功能。
上述中的apiinfo最終都會展現(xiàn)在前端，我們使用了掃描包的方式配置配置，也就是requesthandlerselectors.basepackage。在這個包以及子包中的控制器最終都是生成api文檔。（除了被@apiignore注解指定的請求）。
1.2. 新增文檔說明
上述的類聲明之后，我們其實就可以直接調(diào)用了，但是為了增加文檔的可讀性，我們還是需要在接口中增加一些說明，我們先寫一個控制器如下所示：
|
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
|
@restcontroller@requestmapping(value="/users")public class usercontroller { static map<long, user> users = collections.synchronizedmap(new hashmap<long, user>()); static { user user = new user(); user.setage(18); user.setid(1l); user.setname("aa"); users.put(1l, user); } @apioperation(value="獲取所有用戶列表", notes="") @requestmapping(value={""}, method=requestmethod.get) public list<user> getuserlist() { list<user> r = new arraylist<user>(users.values()); return r; } @apioperation(value="創(chuàng)建新的用戶", notes="根據(jù)user對象創(chuàng)建用戶") @apiimplicitparam(name = "user", value = "用戶詳細實體user", required = true, datatype = "user") @requestmapping(value="", method=requestmethod.post) public string postuser(@requestbody user user) { users.put(user.getid(), user); return "success"; } @apioperation(value="獲取用戶詳細信息", notes="根據(jù)url的id來獲取用戶詳細信息") @apiimplicitparam(name = "id", value = "用戶id", required = true, datatype = "long") @requestmapping(value="/{id}", method=requestmethod.get) public user getuser(@pathvariable long id) { return users.get(id); } @apioperation(value="更新用戶詳細信息", notes="根據(jù)url的id來指定更新對象") @apiimplicitparams({ @apiimplicitparam(name = "id", value = "用戶id", required = true, datatype = "long"), @apiimplicitparam(name = "user", value = "用戶詳細實體user", required = true, datatype = "user") }) @requestmapping(value="/{id}", method=requestmethod.put) public string putuser(@pathvariable long id, @requestbody user user) { user u = users.get(id); u.setname(user.getname()); u.setage(user.getage()); users.put(id, u); return "success"; } @apioperation(value="刪除已存在的用戶", notes="根據(jù)url的id來指定刪除對象") @apiimplicitparam(name = "id", value = "用戶id", required = true, datatype = "long") @requestmapping(value="/{id}", method=requestmethod.delete) public string deleteuser(@pathvariable long id) { users.remove(id); return "success"; }} |
@apioperation：用來描述該接口的作用。可以通過該注解說明接口的職責、返回頭信息、方法的請求方式（"get", "head", "post", "put", "delete", "options" and "patch"）、協(xié)議（ http, https, ws, wss）、http狀態(tài)碼。
@apiimplicitparam：用來給參數(shù)增加說明。可以設置參數(shù)的名稱、是否是必填項、參數(shù)的描述信息、是否只讀等。
上述代碼提交之后，啟動springboot，訪問，如下圖所示：
上圖分為兩個部分，上部分是通過swagger2類配置出來的，下半部分是usercontroller類中的接口文檔。
這里我們以/user為例進行說明：
點擊/user如下圖所示：
上圖黃色的地方表示，該接口返回的樣例數(shù)據(jù)。也就是user的數(shù)據(jù)結構。response content type：接口返回的頭信息。點擊try it out。如下所示：
該接口返回的baody、code碼、響應頭已經(jīng)成功返回了。
總結
以上所述是小編給大家介紹的springboot中集成swagger2框架的方法，希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回復大家的。在此也非常感謝大家對服務器之家網(wǎng)站的支持！
原文鏈接：http://blog.csdn.net/qq_30739519/article/details/78779317
