什么是swagger？
swagger是什么：the world's most popular api tooling
根據官網的介紹：
swagger inspector：測試api和生成openapi的開發工具。swagger inspector的建立是為了解決開發者的三個主要目標。
- 執行簡單的api測試
- 生成openapi文檔
- 探索新的api功能
我的理解swagger是一個規范和完整的框架，用于生成、描述、調用和可視化restful風格的web服務。簡單來說，swagger是一個功能強大的接口管理工具，并且提供了多種編程語言的前后端分離解決方案。根據我的使用，當然我只是最簡單的使用，我感覺swagger有以下幾個優點：
swagger可以整合到代碼中，在開發時通過注解，編寫注釋，自動生成api文檔。
將前端后臺分開，不會有過分的依賴。
界面清晰，無論是editor的實時展示還是ui的展示都十分人性化，如果自己僅僅用markdown來編寫，又要糾結該如何展現，十分痛苦。
構建項目
step1.導入依賴
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
<!--swagger服務api構建個性包--><dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.6.1</version></dependency><!--swagger ui界面--><dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.6.1</version></dependency><!--springboot web服務--><dependency> <groupid>org.springframework.boot</groupid> <artifactid>spring-boot-starter-web</artifactid></dependency><!--springboot單元測試--><dependency> <groupid>org.springframework.boot</groupid> <artifactid>spring-boot-starter-test</artifactid> <scope>test</scope></dependency> |
step2.編寫swagger配置類
想要使用swagger功能必須提供配置類，主要配置ui界面信息，以及配置掃描位置，swagger會根據配置的路徑掃描所有的服務生成api。
其中核心requesthandlerselectors.basepackage("com.simple.spring.boot.controller"),在這里配置我們的需要的掃描包位置。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
@configuration@enableswagger2public class swaggerconfig {@beanpublic docket createrestapi() { return new docket(documentationtype.swagger_2).apiinfo(apiinfo()) .select() .apis(requesthandlerselectors.basepackage("com.simple.spring.boot.controller")) .paths(pathselectors.any()).build();}private apiinfo apiinfo() { return new apiinfobuilder() .title("spring boot中使用swagger2構建restful apis") .description("myapp") .termsofserviceurl("http://blog.csdn.net/simplewu") .version("1.0").build(); }} |
step3.編寫springboot啟動類
@componentscan(basepackages={"com.simple.spring.boot.controller"}) 也是需要配置掃描路徑。
|
1
2
3
4
5
6
7
|
@springbootapplication@componentscan(basepackages={"com.simple.spring.boot.controller"}) public class swaggerapplication { public static void main(string[] args) { springapplication.run(swaggerapplication.class, args); }} |
step4.創建前端控制器
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
@restcontroller@api(tags = "swgger測試服務", description = "swgger測試服務")@requestmapping(value = "/simple/wu")public class testcontroller { @apioperation(value="測試post方法", notes="測試post方法") @apiimplicitparam(name = "令牌", value = "id", required = true, datatype = "token") @requestmapping(value="hello", method=requestmethod.post) public string post(@requestbody string token) { books.put(book.getid(), book); return "success"; }} |
-
@api(tags = "swgger測試服務", description = "swgger測試服務")指定某個類提供服務的名字 -
@apioperation(value="測試post方法", notes="測試post方法")指定某個請求的名字 -
@apiimplicitparam(name = "令牌", value = "token", required = true, datatype = "string")指定名字對應參數為令牌，以及對應參數字段token，required = true代表這個參數為必填參數，datatype 代表數據類型。
step5.啟動服務
從上面的代碼中我們指定請求為post在ui界面上我們會看到一個服務名字為swgger測試服務的大類點擊進去后可以看到里面所擁有的請求，如果指定這個請求的類型那么無法進行單元測試，指定后我們會看到一個請求名字叫做測試post方法的請求并且需要填入必填參數token來完成我們的單元測試。
我們可以直接通過swaggerapplication類來運行main方法來進行服務，端口號默認為8080.
swagger地址：http://localhost:8080/swagger-ui.html 只需要在地址后面加上swagger-ui.html即可訪問
我們訪問這個位置即可看到ui界面，界面簡潔并且容易上手，我這邊就不截圖了。
step.總結
swagger官方文檔:https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
swagger的一個最大的優點是能實時同步api與文檔。
在項目開發過程中，發生過多次：修改代碼但是沒有更新文檔，前端還是按照老舊的文檔進行開發，在聯調過程中才發現問題的情況（當然依據開閉原則，對接口的修改是不允許的，但是在項目不穩定階段，這種情況很難避免）。
總結
以上就是這篇文章的全部內容了，希望本文的內容對大家的學習或者工作具有一定的參考學習價值，如果有疑問大家可以留言交流，謝謝大家對服務器之家的支持。
原文鏈接：https://www.cnblogs.com/SimpleWu/archive/2019/01/12/10261140.html
