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

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

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

傷不起的前后端分離

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

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

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

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

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

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

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

Swagger2是什么？

A Powerful Interface to your API

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

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

SpringBoot整合Swagger2

開始之前呢，按照慣例，先介紹一下開發環境：

Spring Boot 2.1.5
JDK 8
Swagger 2.9.2

接下來咱么就在項目中體驗一下Swagger2,首先我們使用 Intelli IDEA先通過Spring Initializr 創建一個基礎的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/")
// 三個參數分別是姓名，網站，郵箱
.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 設置接口相關實體的描述

創建Controller

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

/***
* SpringBoot整合Swagger2
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用戶相關接口", value = "提供用戶相關的 Rest API")
public class UserController {
/**
* 查找用戶
*
* @param id
* @return
*/
@ApiOperation(value = "查找用戶接口", notes = "根據用戶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: 可設置對控制器的描述。