有了Swagger2 再也不用擔(dān)心API文檔的維護(hù)了

來(lái)源：北大青鳥(niǎo)總部 2023年03月20日 10:48

摘要：今天我們就來(lái)說(shuō)一個(gè)可以提高我們接口文檔開(kāi)發(fā)效率的工具Swagger2。它的出現(xiàn)就是為了解決困擾程序猿的復(fù)雜的、難以維護(hù)的API接口的問(wèn)題。

傷不起的前后端分離

現(xiàn)在互聯(lián)網(wǎng)技術(shù)開(kāi)發(fā)領(lǐng)域，前后端分離開(kāi)發(fā)模式儼然已經(jīng)成為了主流模式，通常情況下后端工程師只需要做好給前端提供數(shù)據(jù)的API接口就可以了，而前端開(kāi)發(fā)工程師則負(fù)責(zé)向后端請(qǐng)求數(shù)據(jù)并渲染頁(yè)面。

這樣做的好處就是后端開(kāi)發(fā)人員只需要關(guān)注后端的業(yè)務(wù)，前端開(kāi)發(fā)人員只需要關(guān)注前端的事情；崗位職責(zé)變得更加清晰，同時(shí)開(kāi)發(fā)效率也大大提升。

在這個(gè)時(shí)候就出現(xiàn)了一個(gè)問(wèn)題，前后端分離后數(shù)據(jù)交互的問(wèn)題，前端開(kāi)發(fā)工程師在去調(diào)用后端接口獲取數(shù)據(jù)的時(shí)候，是要遵循一定的規(guī)則的，比如：傳遞給后端的參數(shù)類(lèi)型等。這個(gè)規(guī)則就是我們常說(shuō)的接口文檔，這個(gè)文檔就定義了前后端數(shù)據(jù)交互時(shí)的規(guī)范。

作為一名程序猿，都或多或少地被接口文檔折磨過(guò)，前端工程師經(jīng)常抱怨后端給的接口文檔與實(shí)際情況不一致；后端工程師總覺(jué)得太多的接口文檔要編寫(xiě)以及維護(hù)接口文檔會(huì)耗費(fèi)不少精力，經(jīng)常來(lái)不及更新。

理想的狀態(tài)應(yīng)該是，編寫(xiě)好的接口文檔同時(shí)發(fā)給前端和后端工程師，大伙按照既定的規(guī)則各自開(kāi)發(fā)就OK了。

而實(shí)際的工作中是經(jīng)常充滿著變化。然而，理想終歸是理想。就像每個(gè)程序猿都會(huì)吐槽別的程序猿為什么總是不寫(xiě)注釋?zhuān)约涸趯?xiě)代碼的時(shí)候又總是很討厭些注釋一樣。

作為一個(gè)愛(ài)動(dòng)腦、愛(ài)思考、技術(shù)特別高超的程序猿群體，但凡我們?cè)诠ぷ饔龅讲凰膯?wèn)題，我們一定會(huì)利用我們“聰明絕頂”的大腦來(lái)把它搞定。今天我們就來(lái)說(shuō)一個(gè)可以提高我們接口文檔開(kāi)發(fā)效率的工具Swagger2。它的出現(xiàn)就是為了解決困擾程序猿的復(fù)雜的、難以維護(hù)的API接口的問(wèn)題。

Swagger2是什么？

A Powerful Interface to your API

Swagger2是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful 風(fēng)格的Web 服務(wù)。它主要包含三部分：

Swagger Codegen: 通過(guò)Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時(shí)也能生成多鐘語(yǔ)言的服務(wù)端和客戶端的代碼。
Swagger UI:提供了一個(gè)可視化的UI頁(yè)面展示描述文件?？梢宰鲆恍┑慕涌谡?qǐng)求。
Swagger Editor: 編輯Swagger描述文件的編輯器，該編輯支持實(shí)時(shí)預(yù)覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。

SpringBoot整合Swagger2

開(kāi)始之前呢，按照慣例，先介紹一下開(kāi)發(fā)環(huán)境：

Spring Boot 2.1.5
JDK 8
Swagger 2.9.2

接下來(lái)咱么就在項(xiàng)目中體驗(yàn)一下Swagger2,首先我們使用 Intelli IDEA先通過(guò)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 的依賴

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

添加Swagger配置類(lèi)

Swagger提供了一個(gè)Docket 對(duì)象，我們可以靈活的配置Swagger 的各項(xiàng)屬性

**
* Swagger配置類(lèi)
*/
@Configuration // 表示這是一個(gè)配置類(lèi)
@EnableSwagger2 // 表示啟用 Swagger2，也可以添加到主啟動(dòng)類(lèi)
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("課工場(chǎng)", "http://www.kgc.cn/", "huan.zhang@kgc.cn"))
//版本號(hào)
.version("1.0")
.build();
}
}

配置實(shí)體類(lèi)

**
* 用戶實(shí)體類(lèi)
*/
@ApiModel(value="用戶對(duì)象",description="用戶對(duì)象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í)體的描述

創(chuàng)建Controller

通過(guò)在控制器類(lèi)上增加@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 + "的用戶成功";
}
}

*@Api: 可設(shè)置對(duì)控制器的描述。