Like Share Discussion Bookmark Smile

J.J. Huang   2019-03-19   Spring Boot   瀏覽次數:

SpringBoot - 第九章 | Swagger2的集成和使用

Spring Boot 能夠快速開發、建置、部署的特性,所以很常被運用在建置RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因,這些終端會共用很多底層業務邏輯,因此我們會抽像出這樣一層來同時服務於多個移動端或者Web前端。

而在現實中RESTful API很有可能要面對多個開發人員或多個開發團隊:IOS開發、Android開發或是Web開發等。為了減少與其他團隊平時開發期間的頻繁溝通成本,傳統做法我們會建立一份RESTful API文件來記錄所有接口細節,然而這樣的做法有以下幾個問題

  • 由於接口眾多,並且細節複雜(需要考慮不同的HTTP請求類型、HTTP頭部訊息、HTTP請求內容等),高質量地建立這份文件本身就是件非常吃力的事。

  • 隨著時間推移,不斷修改接口實現的時候都必須同步修改接口文件,而文件與代碼又處於兩個不同的媒介,除非有嚴格的管理機制,不然很容易導致不一致現象。

本文將介紹RESTful API的重磅好夥伴Swagger2,它可以輕鬆的整合到Spring Boot中,並與Spring MVC程序配合組織出強大RESTful API文件。可以減少我們建立文件的工作量,同時說明內容又整合入實現代碼中,讓維護文件和修改代碼整合為一體,可以讓我們在修改代碼邏輯的同時方便的修改文件說明。另外Swagger2也提供了強大的頁面測試功能來調試每個RESTful API。

Swagger2

以下會使用 第五章 - SpringBoot常用註解 中的 建立RESTful API與單元測試 來做示範

  • Spring Boot中使用Swagger2,需要引入下面依賴
1
2
3
4
5
6
7
8
9
10
<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>
  • 建立Swagger2配置類
    於Application.java同級建立Swagger2的配置類Swagger2

此時其實已經可以生產文件內容。

效果圖片:

但是這樣的文件主要針對請求本身,而描述主要來源於函數等命名產生,對用戶並不友好,我們通常需要自己增加一些說明來豐富文件內容。

  • 增加 Customer 文件內容
  • 增加 CustomerController 文件內容

效果圖片:


文件瀏覽及使用

  • 返回的結果

Swagger上面提供了curl的指令還有Request URL,讓開發者可以快速使用

  • 這邊我們使用查詢客戶列表

可見 Response body ,有剛剛新建的客戶資料

註:以上參考了
程序猿DD-翟永超Spring Boot中使用Swagger2构建强大的RESTful API文档 文章。