Spring Boot 使用 Swagger 2 構建 RESTful APIs 2-10

什麼是 Swagger

Swagger 是一系列 RESTful API 的工具，通過 Swagger 可以獲得項目的一種交互式文檔，客戶端 SDK 的自
動生成等功能。

Swagger 的目標是爲 REST APIs 定義一個標準的、與語⾔言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下，能發現和理解各種服務的功能。當服務通過 Swagger 定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程接口， Swagger 去掉了調用服務時的很多猜測。

Swagger（絲襪哥）是世界上最流行的 API 表達工具。

Swagger 是一個簡單但功能強大的 API 表達工具。它具有地球上最大的 API ⼯工具⽣生態系統，數以千計的開發人員，使用幾乎所有的現代編程語言，都在支持和使用 Swagger。使用 Swagger 生成 API，我們可以得到交互式文檔，自動生成代碼的 SDK 以及 API 的發現特性等。

使用 Spring Boot 集成 Swagger 的理念是，使用註解來標記出需要在 API 文檔中展示的信息， Swagger 會根據項目中標記的註解來生成對應的 API 文檔。 Swagger 被號稱世界上最流行的 API 工具，它提供了 API管理的全套解決方案， API 文檔管理需要考慮的因素基本都包含，這里將講解最常用的定製內容。
 

快速上手

 

Spring Boot 集成 Swagger 2.X 很簡單，需要引入依賴並做基礎配置即可，下⾯面我們來感受一下。

添加依賴包
 

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

創建 SwaggerConfig 配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

在 SwaggerConfig 的類上添加兩個註解：

• @Configuration，啓動時加載此類
• @EnableSwagger2，表示此項目啓用 Swagger API 文檔

在 SwaggerConfig 中添加兩個方法：
 

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// ⾃自⾏行行修改爲⾃自⼰己的包路路徑
.apis(RequestHandlerSelectors.basePackage("com.neo.xxx"))
.paths(PathSelectors.any())
.build();
}

此方法使用 @Bean，在啓動時初始化，返回實例 Docket（Swagger API 摘要），這里需要注意的是
.apis(RequestHandlerSelectors.basePackage("com.neo.xxx")) 指定需要掃描的包路路徑，只有此路徑下的Controller 類纔會自動生成 Swagger API 文檔。
 

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("客戶管理")
.description("客戶管理中⼼心 API 1.0 操作文檔")
//服務條款網址
.termsOfServiceUrl("http://www.ityouknow.com/")
.version("1.0")
.contact(new Contact("純潔的微笑", "http://www.ityouknow.com/", "ityoukn
[email protected]"))
.build();
}

這塊配置相對重要⼀些，主要配置頁面展示的基本信息包括，標題、描述、版本、服務條款、聯繫方式等，查看 ApiInfo 類的源碼還會發現支持 license 配置等。
 

public class ApiInfo {
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
public static final ApiInfo DEFAULT;
private final String version;
private final String title;
private final String description;
private final String termsOfServiceUrl;
private final String license;
private final String licenseUrl;
private final Contact contact;
private final List<VendorExtension> vendorExtensions;
//...
}

以上信息皆可在此方法進行配置，也可以使用默認值。配置完成之後啓動項目，在瀏覽器中輸入網址
http://localhost:8080/swagger-ui.html，即可看到面的配置信息，效果如下：

訪問地址後，發現頁面存在這樣一句話： No operations defined in spec!，意思是沒有找到相關的 API 內容，這是因爲還沒有添加對應的 Controller 信息，接下來結合代碼一一介紹各個註解的使用。
 

Swagger 常用註解

Swagger 通過註解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息等，常⽤用註解內容如下：

作用範圍	API	使用位置
協議集描述	@Api	用於 Controller 類上
協議描述	@ApiOperation	用在 Controller 的方法上
非對象參數集	@ApiImplicitParams	用在 Controller 的方法上
非對象參數描述	@ApiImplicitParam	用在 @ApiImplicitParams 的方法里邊
響應集	@ApiResponses	用在 Controller 的方法上
響應信息參數	@ApiResponse	用在 @ApiResponses 里邊
描述返回對象的意義	@ApiModel	用在返回對象類上
對象屬性	@ApiModelProperty	用在出入參數對象的字段上

在第 2-8 課講解的示例項目基礎上，添加 RESTful API 文檔示例。

@Api 的使用

Api 作用在 Controller 類上，做爲 Swagger 文檔資源，該註解將一個 Controller（Class）標註爲一個Swagger 資源（API）。在默認情況下， Swagger-Core 只會掃描解析具有 @Api 註解的類，而會自動忽略其他類別資源（JAX-RS endpoints、 Servlets 等）的註解。
使用示例：
 

@Api(value = "消息", description = "消息操作 API", position = 100, protocols = "http
")
@RestController
@RequestMapping("/")
public class MessageController {
}

與 Controller 註解並列使用，屬性配置如表所示：

屬性名稱	備註
value	url 的路徑值
tags	如果設置這個值， value 的值會被覆蓋
description	對 API 資源的描述
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss
authorizations	高級特性認證時配置
hidden	配置爲 true 將在文檔中隱藏

重啓項目之後，在瀏覽器中輸入網址 http://localhost:8080/swagger-ui.html#/message-controller，可以看到
如下效果：

自動將 MessageController 內的方法都添加了映射，並標明了每種方法的請求方式。

@ApiOperation 的使用

ApiOperation 定義在方法上，描述方法名、方法解釋、返回信息、標記等信息。
使用示例：

@ApiOperation(
value = "消息列列表",
notes = "完整的消息內容列列表",
produces="application/json, application/xml",
consumes="application/json, application/xml",
response = List.class)
@GetMapping(value = "messages")
public List<Message> list() {
}

屬性名稱	備註
value	url 的路徑值
tags	如果設置這個值、 value的 值會被覆蓋
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss
authorizations	高級特性認證時配置
hidden	配置爲 true 將在文檔中隱藏
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map"，其他無效
httpMethod	"GET"、 "HEAD"、 "POST"、 "PUT"、 "DELETE"、 "OPTIONS" and "PATCH"
code	http 的狀態碼 默認 200
extensions	擴展屬性

重啓項目之後，在瀏覽器中輸入網址 http://localhost:8080/swagger-ui.html#/messagecontroller/listUsingGET，可以看到如下效果：

@ApiImplicitParams 和 @ApiImplicitParam 的使用

@ApiImplicitParams 用於描述方法的返回信息，和 @ApiImplicitParam 註解配合使用； @ApiImplicitParam
用來描述具體某一個參數的信息，包括參數的名稱、類型、限制等信息。
使用示例：
 

@ApiOperation(value = "添加消息", notes = "根據參數創建消息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "消息 ID", required = true, data
Type = "Long", paramType = "query"),
@ApiImplicitParam(name = "text", value = "正⽂文", required = true, dataT
ype = "String", paramType = "query"),
@ApiImplicitParam(name = "summary", value = "摘要", required = false, d
ataType = "String", paramType = "query"),
})
@PostMapping(value = "message")
public Message create(Message message) {
}

屬性名稱	備註
name	接收參數名
value	接收參數的意義描述
required	參數是否必填值爲 true 或者 false
dataType	參數的數據類型只作爲標誌說明，並沒有實際驗證
paramType	查詢參數類型，其值： path 以地址的形式提交數據 query 直接跟參數完成自動映射賦 body 以流的形式提交，僅支持 POST header 參數在 request headers 里邊提交 form 以 form 表單的形式提交 僅支持 POST
defaultValue	默認值

重啓項目之後，在瀏覽器中輸入網址 http://localhost:8080/swagger-ui.html#/messagecontroller/createUsingPOST，可以看到如下效果：

@ApiResponses 和 @ApiResponse 的使用

@ApiResponses 主要封裝方法的返回信息和 @ApiResponse 配置起來使用， @ApiResponse 定義返回的具
體信息包括返回碼、返回信息等。
使用示例：

@ApiOperation(value = "修改消息", notes = "根據參數修改消息")
@PutMapping(value = "message")
@ApiResponses({
@ApiResponse(code = 100, message = "請求參數有誤"),
@ApiResponse(code = 101, message = "未授權"),
@ApiResponse(code = 103, message = "禁⽌止訪問"),
@ApiResponse(code = 104, message = "請求路徑不存在"),
@ApiResponse(code = 200, message = "服務器內部錯誤")
})
public Message modify(Message message) {
}

屬性名稱	備註
code	http 的狀態碼
message	描述
response	默認響應類 Void
reference	參考
responseHeaders	封裝返回信息
responseContainer	字符串串

重啓項目之後，在瀏覽器中輸入網址 http://localhost:8080/swagger-ui.html#/messagecontroller/modifyUsingPUT，可以看到如下效果：

@ApiModel 和 @ApiModelProperty 的使用

在實際的項目中我們常會封裝一個對象作爲返回值， @ApiModel 就是負責描述對象的信息，
@ApiModelProperty 負責描述對象中屬性的相關內容。
使用示例：
 

@ApiModel(description = "響應對象")
public class BaseResult<T> {
private static final int SUCCESS_CODE = 0;
private static final String SUCCESS_MESSAGE = "成功";
@ApiModelProperty(value = "響應碼", name = "code", required = true, example = "
" + SUCCESS_CODE)
private int code;
@ApiModelProperty(value = "響應消息", name = "msg", required = true, example = S
UCCESS_MESSAGE)
private String msg;
@ApiModelProperty(value = "響應數據", name = "data")
private T data;
}

屬性配置如下表所示：

屬性名稱	備註
value	屬性描述
name	如果配置覆蓋屬性名稱
allowableValues	允許的值
access	可以不配置
notes	沒有使用
dataType	數據類型
required	是否爲必傳參數
position	顯示的順序位置
hidden	是否因此
example	舉例例
readOnly	只讀
reference	引用

這樣我們在 Controller 中封裝返還信息時就可以這樣操作：
 

@PatchMapping(value="/message/text")
public BaseResult<Message> patch(Message message) {
Message messageResult=this.messageRepository.updateText(message);
return BaseResult.successWithData(messageResult);
}

重啓項目之後，在瀏覽器中輸入網址 http://localhost:8080/swagger-ui.html，點解頁面 Models 摺疊項，可以
看到如下效果：

以上就是在項目中最常用的一些註解，靈活地利用這些註解就可以自動構建出清晰的 API 文檔。

Try it out

使⽤用 Swagger 創建的在線 API 還有一個非常強大的功能，可以在頁面直接測試接口的可用性，這樣在前端和後端接口調試出現問題時，可以非常方便地利用此功能進行接口驗證。在上面參數講解過程中，我們發現每個接口描述右側都有一個按鈕 try it out，單擊 try it out 按鈕即可進入表單頁面，如下：

在表單頁面添加相關字段後，單擊“Execute”按鈕就會將請求發送到後臺，從而進行接口驗證，通過按鈕下面的命令可以看出，實際上是使用了 curl 命令進行的 post 測試：

curl -X POST "http://localhost:8080/message?id=6&summary=%E8%BF%99%E6%98%AF%E4%B8%
80%E4%B8%AA%E6%B6%88%E6%81%AF&text=hello" -H "accept: */*"

在後端調整 Swagger 方法上對應參數，即可看到 curl 命令參數的變化。
 

總結

通過這節課的學習我們掌握了在 Spring Boot 項目中使用 Swagger，利用 Swagger 的相關注解可以容易地構建出豐富的 API 文檔。使用 Swagger 之後可以幫助生成標準的 API 說明文檔，避免接口交互中的低效溝通問題， Swagger 做爲強大的 API 生成框架其實還有更多的功能，大家有機會可以在線下繼續學習。
點擊這⾥下載源碼