摘要：
Swagger2是什么？Swagger2對于程序員們有什么便捷呢？
現(xiàn)在互聯(lián)網(wǎng)技術(shù)開發(fā)領(lǐng)域，前后端分離開發(fā)模式儼然已經(jīng)成為了主流模式，通常情況下后端工程師只需要做好給前端提供數(shù)據(jù)的API接口就可以了，而前端開發(fā)工程師則負(fù)責(zé)向后端請求數(shù)據(jù)并渲染頁面。
這樣做的好處就是后端開發(fā)人員只需要關(guān)注后端的業(yè)務(wù)，前端開發(fā)人員只需要關(guān)注前端的事情；崗位職責(zé)變得更加清晰，同時(shí)開發(fā)效率也大大提升。
在這個(gè)時(shí)候就出現(xiàn)了一個(gè)問題，前后端分離后數(shù)據(jù)交互的問題，前端開發(fā)工程師在去調(diào)用后端接口獲取數(shù)據(jù)的時(shí)候，是要遵循一定的規(guī)則的，比如：傳遞給后端的參數(shù)類型等。這個(gè)規(guī)則就是我們常說的接口文檔，這個(gè)文檔就定義了前后端數(shù)據(jù)交互時(shí)的規(guī)范。
作為一名程序猿，都或多或少地被接口文檔折磨過，前端工程師經(jīng)常抱怨后端給的接口文檔與實(shí)際情況不一致；后端工程師總覺得太多的接口文檔要編寫以及維護(hù)接口文檔會(huì)耗費(fèi)不少精力，經(jīng)常來不及更新。
理想的狀態(tài)應(yīng)該是，編寫好的接口文檔同時(shí)發(fā)給前端和后端工程師，大伙按照既定的規(guī)則各自開發(fā)就OK了。
而實(shí)際的工作中是經(jīng)常充滿著變化。然而，理想終歸是理想。就像每個(gè)程序猿都會(huì)吐槽別的程序猿為什么總是不寫注釋，而自己在寫代碼的時(shí)候又總是很討厭些注釋一樣。
作為一個(gè)愛動(dòng)腦、愛思考、技術(shù)特別高超的程序猿群體，但凡我們在工作遇到不爽的問題，我們一定會(huì)利用我們“聰明絕頂”的大腦來把它搞定。今天我們就來說一個(gè)可以提高我們接口文檔開發(fā)效率的工具Swagger2。它的出現(xiàn)就是為了解決困擾程序猿的復(fù)雜的、難以維護(hù)的API接口的問題。
Swagger2是什么？
A Powerful Interface to your API
Swagger2是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful 風(fēng)格的Web 服務(wù)。它主要包含三部分：
Swagger Codegen: 通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時(shí)也能生成多鐘語言的服務(wù)端和客戶端的代碼。
Swagger UI:提供了一個(gè)可視化的UI頁面展示描述文件。可以做一些的接口請求。
Swagger Editor: 編輯Swagger描述文件的編輯器，該編輯支持實(shí)時(shí)預(yù)覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。SpringBoot整合Swagger2
開始之前呢，按照慣例，先介紹一下開發(fā)環(huán)境：
Spring Boot 2.1.5
JDK 8
Swagger 2.9.2
接下來咱么就在項(xiàng)目中體驗(yàn)一下Swagger2,首先我們使用 Intelli IDEA先通過Spring Initializr 創(chuàng)建一個(gè)基礎(chǔ)的SpringBoot 項(xiàng)目。并且添加web的依賴，因?yàn)槲覀兪荝ESTful風(fēng)格的API。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId></dependency>
添加Swagger 的依賴
<!--swagger的依賴--><dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version></dependency><!--swagger-ui可視化依賴,如果不添加此依賴，測試的結(jié)果是json格式的數(shù)據(jù)--><dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version></dependency>
添加Swagger配置類
Swagger提供了一個(gè)Docket 對象，我們可以靈活的配置Swagger 的各項(xiàng)屬性
**
* Swagger配置類
*/
@Configuration // 表示這是一個(gè)配置類@EnableSwagger2 // 表示啟用 Swagger2，也可以添加到主啟動(dòng)類public class Swagger2Config {
@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.*"))
.paths(PathSelectors.any())
.build();
} // API的詳細(xì)信息
private ApiInfo apiInfo() { return new ApiInfoBuilder() //標(biāo)題
.title("Springboot整合swagger2") //描述
.description("swagger2生成Restful風(fēng)格API接口文檔")
.termsOfServiceUrl("http://www.kgc.cn/") // 三個(gè)參數(shù)分別是姓名，網(wǎng)站，郵箱
.contact(new Contact("課工場", "http://www.kgc.cn/", "huan.zhang@kgc.cn")) //版本號
.version("1.0")
.build();
}
}
配置實(shí)
**
* 用戶實(shí)體類
*/
@ApiModel(value="用戶對象",description="用戶對象user")public class User implements Serializable {
@ApiModelProperty(name = "用戶id",value = "用戶id") private Integer id; // 用戶id
@ApiModelProperty(name = "用戶name",value = "用戶名") private String username; //用戶名
@ApiModelProperty(name = "用戶age",value = "年齡") private Integer age; // 年齡
// 省略setter 、getter方法和構(gòu)造器方法}
@ApiModel 設(shè)置接口相關(guān)實(shí)體的描述
通過在控制器類上增加@Api注解，給控制器增加描述和標(biāo)簽信息。
/*** * SpringBoot整合Swagger2
*/ @RestController
@RequestMapping("/user")
@Api(tags = "用戶相關(guān)接口", value = "提供用戶相關(guān)的 Rest API")
public class UserController { /**
* 查找用戶
*
* @param id
* @return
*/
@ApiOperation(value = "查找用戶接口", notes = "根據(jù)用戶id查找用戶信息")
@GetMapping("/find/{id}")
public User findById(@ApiParam(name = "id", value = "用戶id", required = true)
@PathVariable("id")
int id) { return new User(id, "小課", 18);
} /**
* 刪除用戶信息
*
* @param id
* @return
*/
@ApiOperation(value = "刪除用戶接口", notes = "刪除用戶")
@DeleteMapping("/delete/{id}")
public String delete(@PathVariable("id") int id) { return "刪除用戶id：" + id + "的用戶成功";
} /**
* 更新用戶信息
*
* @param user
* @return
*/
@ApiOperation(value = "更新用戶接口", notes = "更新用戶")
@PutMapping("/update")
public String update(@RequestBody User user) { return "更新用戶id：" + id + "的用戶成功";
} /**
* 添加用戶
*
* @param user
* @return
*/
@ApiOperation(value = "新增用戶接口", notes = "新增用戶")
@PostMapping("/add")
public String addUser(@RequestBody User user) { return "添加用戶id：" + id + "的用戶成功";
}
}
我們啟動(dòng)一下項(xiàng)目，然后在瀏覽器中訪問http://localhost:8080/swagger-ui.html 就可以看到如下的效果啦！
點(diǎn)開查找用戶接口，點(diǎn)擊Tryit out，
這樣幾步我們就完成了，SpringBoot整合Swagger2的案例，相信大家都已經(jīng)能夠體會(huì)到Swagger2對于程序員們的的便捷，趕緊動(dòng)手實(shí)戰(zhàn)吧
到這里我們Swagger2的內(nèi)容就搞定了，恭喜你有Get了一個(gè)新技能。
京公網(wǎng)安備 11010802020714號
京ICP備2020047077號-2
手機(jī)端官網(wǎng)
