Spring Boot 集成 Swagger2 展現(xiàn)在線接口文檔
本來已收錄到我寫的10萬字Springboot經(jīng)典學(xué)習(xí)筆記中，筆記在持續(xù)更新……文末有領(lǐng)取方式
1. Swagger 簡介
1.1 解決的問題
隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來的后端渲染，變成了前后端分離的形態(tài)，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠(yuǎn)。前端和后端的唯一聯(lián)系，變成了 API 接口，所以 API 文檔變成了前后端開發(fā)人員聯(lián)系的紐帶，變得越來越重要。
那么問題來了，隨著代碼的不斷更新，開發(fā)人員在開發(fā)新的接口或者更新舊的接口后，由于開發(fā)任務(wù)的繁重，往往文檔很難持續(xù)跟著更新，Swagger 就是用來解決該問題的一款重要的工具，對使用接口的人來說，開發(fā)人員不需要給他們提供文檔，只要告訴他們一個 Swagger 地址，即可展示在線的 API 接口文檔，除此之外，調(diào)用接口的人員還可以在線測試接口數(shù)據(jù)，同樣地，開發(fā)人員在開發(fā)接口時，同樣也可以利用 Swagger 在線接口文檔測試接口數(shù)據(jù)，這給開發(fā)人員提供了便利。
1.2 Swagger 官方
我們打開 Swagger 官網(wǎng)，官方對 Swagger 的定義為：
The Best APIs are Built with Swagger Tools
翻譯成中文是：“最好的 API 是使用 Swagger 工具構(gòu)建的”。由此可見，Swagger 官方對其功能和所處的地位非常自信，由于其非常好用，所以官方對其定位也合情合理。如下圖所示：
本文主要講解在 Spring Boot 中如何導(dǎo)入 Swagger2 工具來展現(xiàn)項目中的接口文檔。本節(jié)課使用的 Swagger 版本為 2.2.2。下面開始進入 Swagger2 之旅。
2. Swagger2 的 maven 依賴
使用 Swagger2 工具，必須要導(dǎo)入 maven 依賴，當(dāng)前官方最高版本是 2.8.0，我嘗試了一下，個人感覺頁面展示的效果不太好，而且不夠緊湊，不利于操作。另外，最新版本并不一定是最穩(wěn)定版本，當(dāng)前我們實際項目中使用的是 2.2.2 版本，該版本穩(wěn)定，界面友好，所以本節(jié)課主要圍繞著 2.2.2 版本來展開，依賴如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
3. Swagger2 的配置
使用 Swagger2 需要進行配置，Spring Boot 中對 Swagger2 的配置非常方便，新建一個配置類，Swagger2 的配置類上除了添加必要的 @Configuration 注解外，還需要添加 @EnableSwagger2 注解。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author shengwu ni
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 指定構(gòu)建api文檔的詳細(xì)信息的方法：apiInfo()
.apiInfo(apiInfo())
.select()
// 指定要生成api接口的包路徑，這里把controller作為包路徑，生成controller中的所有接口
.apis(RequestHandlerSelectors.basePackage("com.itcodai.course06.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 構(gòu)建api文檔的詳細(xì)信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 設(shè)置頁面標(biāo)題
.title("Spring Boot集成Swagger2接口總覽")
// 設(shè)置接口描述
.description("跟武哥一起學(xué)Spring Boot第06課")
// 設(shè)置聯(lián)系方式
.contact("倪升武，" + "CSDN：http://blog.csdn.net/eson_15")
// 設(shè)置版本
.version("1.0")
// 構(gòu)建
.build();
}
}
在該配置類中，已經(jīng)使用注釋詳細(xì)解釋了每個方法的作用了，在此不再贅述。到此為止，我們已經(jīng)配置好了 Swagger2 了?，F(xiàn)在我們可以測試一下配置有沒有生效，啟動項目，在瀏覽器中輸入 localhost:8080/swagger-ui.html，即可看到 swagger2 的接口頁面，如下圖所示，說明Swagger2 集成成功。
結(jié)合該圖，對照上面的 Swagger2 配置文件中的配置，可以很明確的知道配置類中每個方法的作用。這樣就很容易理解和掌握 Swagger2 中的配置了，也可以看出，其實 Swagger2 配置很簡單。
4. Swagger2 的使用
上面我們已經(jīng)配置好了 Swagger2，并且也啟動測試了一下，功能正常，下面我們開始使用 Swagger2，主要來介紹 Swagger2 中的幾個常用的注解，分別在實體類上、 Controller 類上以及 Controller 中的方法上，最后我們看一下 Swagger2 是如何在頁面上呈現(xiàn)在線接口文檔的，并且結(jié)合 Controller 中的方法在接口中測試一下數(shù)據(jù)。
4.1 實體類注解
本節(jié)我們建一個 User 實體類，主要介紹一下 Swagger2 中的 @ApiModel 和 @ApiModelProperty 注解，同時為后面的測試做準(zhǔn)備。
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "用戶實體類")
public class User {
@ApiModelProperty(value = "用戶唯一標(biāo)識")
private Long id;
@ApiModelProperty(value = "用戶姓名")
private String username;
@ApiModelProperty(value = "用戶密碼")
private String password;
// 省略set和get方法
}
解釋下 @ApiModel 和 @ApiModelProperty 注解：
@ApiModel注解用于實體類，表示對類進行說明，用于參數(shù)用實體類接收。@ApiModelProperty注解用于類中屬性，表示對 model 屬性的說明或者數(shù)據(jù)操作更改。
該注解在在線 API 文檔中的具體效果在下文說明。
4.2 Controller 類中相關(guān)注解
我們寫一個 TestController，再寫幾個接口，然后學(xué)習(xí)一下 Controller 中和 Swagger2 相關(guān)的注解。
import com.itcodai.course06.entiy.JsonResult;
import com.itcodai.course06.entiy.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在線接口文檔")
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根據(jù)用戶唯一標(biāo)識獲取用戶信息")
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用戶唯一標(biāo)識") Long id) {
// 模擬數(shù)據(jù)庫中根據(jù)id獲取User信息
User user = new User(id, "倪升武", "123456");
return new JsonResult(user);
}
}
我們來學(xué)習(xí)一下 @Api 、 @ApiOperation 和 @ApiParam 注解。
@Api注解用于類上，表示標(biāo)識這個類是 swagger 的資源。@ApiOperation注解用于方法，表示一個 http 請求的操作。@ApiParam注解用于參數(shù)上，用來標(biāo)明參數(shù)信息。
這里返回的是 JsonResult，是第02課中學(xué)習(xí)返回 json 數(shù)據(jù)時封裝的實體。以上是 Swagger 中最常用的 5 個注解，接下來運行一下項目工程，在瀏覽器中輸入 localhost:8080/swagger-ui.html 看一下 Swagger 頁面的接口狀態(tài)。
可以看出，Swagger 頁面對該接口的信息展示的非常全面，每個注解的作用以及展示的地方在上圖中已經(jīng)標(biāo)明，通過頁面即可知道該接口的所有信息，那么我們直接在線測試一下該接口返回的信息，輸入id為1，看一下返回數(shù)據(jù)：
可以看出，直接在頁面返回了 json 格式的數(shù)據(jù)，開發(fā)人員可以直接使用該在線接口來測試數(shù)據(jù)的正確與否，非常方便。上面是對于單個參數(shù)的輸入，如果輸入?yún)?shù)為某個對象這種情況，Swagger 是什么樣子呢？我們再寫一個接口。
@PostMapping("/insert")
@ApiOperation(value = "添加用戶信息")
public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用戶信息") User user) {
// 處理添加邏輯
return new JsonResult<>();
}
重啟項目，在瀏覽器中輸入 localhost:8080/swagger-ui.html 看一下效果：
5. 總結(jié)
OK，本節(jié)課詳細(xì)分析了 Swagger 的優(yōu)點，以及 Spring Boot 如何集成 Swagger2，包括配置，相關(guān)注解的講解，涉及到了實體類和接口類，以及如何使用。最后通過頁面測試，體驗了 Swagger 的強大之處，基本上是每個項目組中必備的工具之一，所以要掌握該工具的使用，也不難。
該文已收錄到我寫的《10萬字Springboot經(jīng)典學(xué)習(xí)筆記》中，點擊下方小卡片，進入【武哥聊編程】，回復(fù)：筆記，即可免費獲取。
點贊是最大的支持
