有了Swagger2 再也不用擔心API文檔的維護了

來源：北大青鳥總部 2023年03月20日 10:48

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

傷不起的前后端分離

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

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

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

作為一名程序猿，都或多或少地被接口文檔折磨過，前端工程師經(jīng)常抱怨后端給的接口文檔與實際情況不一致；后端工程師總覺得太多的接口文檔要編寫以及維護接口文檔會耗費不少精力，經(jīng)常來不及更新。

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

而實際的工作中是經(jīng)常充滿著變化。然而，理想終歸是理想。就像每個程序猿都會吐槽別的程序猿為什么總是不寫注釋，而自己在寫代碼的時候又總是很討厭些注釋一樣。

作為一個愛動腦、愛思考、技術特別高超的程序猿群體，但凡我們在工作遇到不爽的問題，我們一定會利用我們“聰明絕頂”的大腦來把它搞定。今天我們就來說一個可以提高我們接口文檔開發(fā)效率的工具Swagger2。它的出現(xiàn)就是為了解決困擾程序猿的復雜的、難以維護的API接口的問題。

Swagger2是什么？

A Powerful Interface to your API

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

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

SpringBoot整合Swagger2

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

Spring Boot 2.1.5
JDK 8
Swagger 2.9.2

接下來咱么就在項目中體驗一下Swagger2,首先我們使用 Intelli IDEA先通過Spring Initializr 創(chuàng)建一個基礎的SpringBoot 項目。并且添加web的依賴，因為我們是RESTful風格的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配置類

Swagger提供了一個Docket 對象，我們可以靈活的配置Swagger 的各項屬性

**
* Swagger配置類
*/
@Configuration // 表示這是一個配置類
@EnableSwagger2 // 表示啟用 Swagger2，也可以添加到主啟動類
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的詳細信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//標題
.title("Springboot整合swagger2")
//描述
.description("swagger2生成Restful風格API接口文檔")
.termsOfServiceUrl("http://www.kgc.cn/")
// 三個參數(shù)分別是姓名，網(wǎng)站，郵箱
.contact(new Contact("課工場", "http://www.kgc.cn/", "huan.zhang@kgc.cn"))
//版本號
.version("1.0")
.build();
}
}

配置實體類

**
* 用戶實體類
*/
@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方法和構造器方法
}

@ApiModel 設置接口相關實體的描述

創(chuàng)建Controller

通過在控制器類上增加@Api注解，給控制器增加描述和標簽信息。

/***
* SpringBoot整合Swagger2
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用戶相關接口", value = "提供用戶相關的 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: 可設置對控制器的描述。