六、Spring Boot 集成 Swagger2 展 現在線接口文檔

前言:上一節對 SpringBoot 的Spring Boot 中的 MVC 支持做了一個介紹,本節主要對Spring Boot 集成 Swagger2 展現在線接口文檔講解和分析。

1. Swagger 簡介

1.1 解決的問題

隨着互聯網技術的發展,現在的網站架構基本都由原來的後端渲染,變成了前後端分離的形態,而且前端技術和後端技術在各自的道路上越走越遠。前端和後端的唯一聯繫, 變成了 API 接口,所以 API 文檔變成了前後端開發人員聯繫的紐帶,變得越來越重要

那麼問題來了,隨着代碼的不斷更新,開發人員在開發新的接口或者更新舊的接口後, 由於開發任務的繁重,往往文檔很難持續跟着更新,Swagger 就是用來解決該問題的 一款重要的工具,對使用接口的人來說,開發人員不需要給他們提供文檔,只要告訴他 們一個 Swagger 地址,即可展示在線的 API 接口文檔,除此之外,調用接口的人員還可以在線測試接口數據,同樣地,開發人員在開發接口時,同樣也可以利用 Swagger 在線接口文檔測試接口數據,這給開發人員提供了便利。

1.2 Swagger 官方

我們打開 Swagger 官網,官方對 Swagger 的定義爲:

The Best APIs are Built with Swagger Tools

翻譯成中文是:“最好的 API 是使用 Swagger 工具構建的”。由此可見,Swagger 官方 對其功能和所處的地位非常自信,由於其非常好用,所以官方對其定位也合情合理。如下圖所示:

本文主要講解在 Spring Boot 中如何導入 Swagger2 工具來展現項目中的接口文檔。本節課使用的 Swagger 版本爲 2.2.2。下面開始進入 Swagger2 之旅。

2. Swagger2 的 maven 依賴

使用 Swagger2 工具,必須要導入 maven 依賴,當前官方最高版本我嘗試了一下,個人感覺頁面展示的效果不太好,而且不夠緊湊,不利於操作。另外,最新版本並不一定是最穩定版本,當前我們實際項目中使用的是 2.2.2 版本,該版本穩定,界面 友好,所以本節課主要圍繞着 2.2.2 版本來展開,依賴如下:

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

3. Swagger2 的配置

使用 Swagger2 需要進行配置,Spring Boot 中對 Swagger2 的配置非常方便,新建一 個配置類Swagger2 的配置類上除了添加必要的 @Configuration 註解外,還需要添 加 @EnableSwagger2 註解。

[@Configuration](https://my.oschina.net/pointdance)
@EnableSwagger2
public class SwaggerConfig {

	[@Bean](https://my.oschina.net/bean)
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				// 指定構建api文檔的詳細信息的方法:apiInfo()
				.apiInfo(apiInfo())
				.select()
				// 指定要生成api接口的包路徑,這裏把controller作爲包路徑,生成controller中的所有接口
				.apis(RequestHandlerSelectors.basePackage("com.itcodai.course06.controller"))
				.paths(PathSelectors.any())
				.build();
	}

	/**
	 * 構建api文檔的詳細信息
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 設置頁面標題
				.title("Spring Boot集成Swagger2接口總覽")
				// 設置接口描述
				.description("一起學Spring Boot第06課")
				// 設置聯繫方式
				.contact("理性思考," + "os:https://my.oschina.net/lixingsikao")
				// 設置版本
				.version("1.0")
				// 構建
				.build();
	}
}

在該配置類中,已經使用註釋詳細解釋了每個方法的作用了,在此不再贅述。到此爲止,我們已經配置好了 Swagger2 了。現在我們可以測試一下配置有沒有生效,啓動項 目,在瀏覽器中輸入 localhost:8080/swagger-ui.html,即可看到 swagger2 的接 口頁面,如下圖所示,說明 Swagger2 集成成功。

結合該圖,對照上面的 Swagger2 配置文件中的配置,可以很明確的知道配置類中每個 方法的作用。這樣就很容易理解和掌握 Swagger2 中的配置了,也可以看出,其實 Swagger2 配置很簡單。

【友情提示】可能有很多朋友在配置 Swagger 的時候會遇到下面的情況,
而且還關不 掉的,這是因爲瀏覽器緩存引起的,清空一下瀏覽器緩存即可解決問題。

4. Swagger2 的使用

上面我們已經配置好了 Swagger2,並且也啓動測試了一下,功能正常,下面我們開始 使用 Swagger2,主要來介紹 Swagger2 中的幾個常用的註解,分別在實體類上、 Controller 類上以及 Controller 中的方法上,最後我們看一下 Swagger2 是如何在頁面上呈現在線接口文檔的,並且結合 Controller 中的方法在接口中測試一下數據。

4.1 實體類註解

本節我們建一個 User 實體類,主要介紹一下 Swagger2 中的 @ApiModel@ApiModelProperty 註解,同時爲後面的測試做準備。

@ApiModel(value = "用戶實體類")
public class User {

	@ApiModelProperty(value = "用戶唯一標識")
	private Long id;

	@ApiModelProperty(value = "用戶姓名")
	private String username;

	@ApiModelProperty(value = "用戶密碼")
	private String password;
	//set  get 忽略
}

解釋下 @ApiModel@ApiModelProperty 註解:

@ApiModel 註解用於實體類,表示對類進行說明,用於參數用 實體類接收。 @ApiModelProperty 註解用於類中屬性,表示對 model 屬性的說明或者數據操作更改。

該註解在在線 API 文檔中的具體效果在下文說明。

4.2 Controller 類中相關注解

我們寫一個 TestController,再寫幾個接口,然後學習一下 Controller 中和 Swagger2 相關的註解。

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在線接口文檔--lxsk")
public class TestController {

	@GetMapping("/get/{id}")
	@ApiOperation(value = "根據用戶唯一標識獲取用戶信息")
	public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用戶唯一標識") Long id) {
		// 模擬數據庫中根據id獲取User信息
		User user = new User(id, "理性思考", "123456");
		return new JsonResult(user);
	}

}   

我們來學習一下 @Api 、 @ApiOperation 和 @ApiParam 註解。

  • @Api 註解用於類上,表示標識這個類是 swagger 的資源。
  • @ApiOperation 註解用於方法,表示一個 http 請求的操作。
  • @ApiParam 註解用於參數上,用來標明參數信息。

這裏返回的是 JsonResult,是第 02 課中學習返回 json 數據時封裝的實體。以上是 Swagger 中最常用的 5 個註解,接下來運行一下項目工程,在瀏覽器中輸入 localhost:8080/swagger-ui.html 看一下 Swagger 頁面的接口狀態。

可以看出,Swagger 頁面對該接口的信息展示的非常全面,每個註解的作用以及展示 的地方在上圖中已經標明,通過頁面即可知道該接口的所有信息,那麼我們直接在線測 試一下該接口返回的信息,輸入 id 爲 1,看一下返回數據:

可以看出,直接在頁面返回了 json 格式的數據,開發人員可以直接使用該在線接口來 測試數據的正確與否,非常方便。上面是對於單個參數的輸入,如果輸入參數爲某個對象這種情況,Swagger 是什麼樣子呢?我們再寫一個接口。

重啓項目,在瀏覽器中輸入 localhost:8080/swagger-ui.html 看一下效果:

5. 總結

OK,本節課詳細分析了 Swagger 的優點,以及 Spring Boot 如何集成 Swagger2,包括配置,相關注解的講解,涉及到了實體類和接口類,以及如何使用。最後通過頁面測試,體驗了 Swagger 的強大之處,基本上是每個項目組中必備的工具之一,所以要掌握該工具的使用,也不難。


堅持每天進步一點點!

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章