Swagger 是一個(gè)簡(jiǎn)單但功能強(qiáng)大的 API 表達(dá)工具。它具有地球上最大的 API 工具生態(tài)系統(tǒng)，數(shù)以千計(jì)的開發(fā)人員，使用幾乎所有的現(xiàn)代編程語言，都在支持和使用 Swagger。使用 Swagger 生成 API，我們可以得到交互式文檔，自動(dòng)生成代碼的 SDK 以及 API 的發(fā)現(xiàn)特性等。
使用 Spring Boot 集成 Swagger 的理念是，使用注解來標(biāo)記出需要在 API 文檔中展示的信息，Swagger 會(huì)根據(jù)項(xiàng)目中標(biāo)記的注解來生成對(duì)應(yīng)的 API 文檔。Swagger 被號(hào)稱世界上最流行的 API 工具，它提供了 API 管理的全套解決方案，API 文檔管理需要考慮的因素基本都包含，這里將講解最常用的定制內(nèi)容。
環(huán)境以及版本：
SpringBoot ： 2.0.5.RELEASE
JDK ：1.8
maven 依賴
<!--swagger2-->
<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>
創(chuàng)建 SwaggerConfig 配置類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
然后添加
在 SwaggerConfig 的類上添加兩個(gè)注解：
@Configuration，啟動(dòng)時(shí)加載此類
@EnableSwagger2，表示此項(xiàng)目啟用 Swagger API 文檔
在 SwaggerConfig 中添加兩個(gè)方法：
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 自行修改為自己的包路徑
.apis(RequestHandlerSelectors.basePackage("com.neo.xxx"))
.paths(PathSelectors.any())
.build();
}
主要配置頁(yè)面展示的基本信息包括，標(biāo)題、描述、版本、服務(wù)條款、聯(lián)系方式等，查看 ApiInfo 類的源碼還會(huì)發(fā)現(xiàn)支持 license 配置等。
啟動(dòng)后
訪問地址可以看到
還可以進(jìn)行測(cè)試
結(jié)果
Swagger 常用注解
Swagger 通過注解表明該接口會(huì)生成文檔，包括接口名、請(qǐng)求方法、參數(shù)、返回信息等，常用注解內(nèi)容如下：
作用范圍 API 使用位置
協(xié)議集描述 @Api 用于 Controller 類上
協(xié)議描述 @ApiOperation 用在 Controller 的方法上
非對(duì)象參數(shù)集 @ApiImplicitParams 用在 Controller 的方法上
非對(duì)象參數(shù)描述 @ApiImplicitParam 用在 @ApiImplicitParams 的方法里邊
響應(yīng)集 @ApiResponses 用在 Controller 的方法上
響應(yīng)信息參數(shù) @ApiResponse 用在 @ApiResponses 里邊
描述返回對(duì)象的意義 @ApiModel 用在返回對(duì)象類上
對(duì)象屬性 @ApiModelProperty 用在出入?yún)?shù)對(duì)象的字段上
@Api 的使用
Api 作用在 Controller 類上，做為 Swagger 文檔資源，該注解將一個(gè) Controller（Class）標(biāo)注為一個(gè) Swagger 資源（API）。在默認(rèn)情況下，Swagger-Core 只會(huì)掃描解析具有 @Api 注解的類，而會(huì)自動(dòng)忽略其他類別資源（JAX-RS endpoints、Servlets 等）的注解。
@Api(value = "驗(yàn)證測(cè)試",description = "驗(yàn)證數(shù)據(jù)",consumes = "application/json",produces = "http",hidden = true)
@RestController
public class validController {
與 Controller 注解并列使用，屬性配置如表所示：
屬性名稱 備注
value url 的路徑值
tags 如果設(shè)置這個(gè)值，value 的值會(huì)被覆蓋
description 對(duì) API 資源的描述
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss
authorizations 高級(jí)特性認(rèn)證時(shí)配置
hidden 配置為 true 將在文檔中隱藏
@ApiOperation 的使用
ApiOperation 定義在方法上，描述方法名、方法解釋、返回信息、標(biāo)記等信息。
@ApiOperation(
value = "save 消息列表",
notes = "save 完整的消息內(nèi)容列表",
produces="application/www-xxxxx, application/xml",
consumes="application/json, application/xml",
response = List.class
)
屬性名稱 備注
value url 的路徑值
tags 如果設(shè)置這個(gè)值、value的 值會(huì)被覆蓋
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss
authorizations 高級(jí)特性認(rèn)證時(shí)配置
hidden 配置為 true 將在文檔中隱藏
response 返回的對(duì)象
responseContainer 這些對(duì)象是有效的 "List", "Set" or "Map"，其他無效
httpMethod "GET"、"HEAD"、"POST"、"PUT"、"DELETE"、"OPTIONS" and "PATCH"
code http 的狀態(tài)碼 默認(rèn) 200
extensions 擴(kuò)展屬性
@ApiImplicitParams 和 @ApiImplicitParam 的使用
@ApiImplicitParams 用于描述方法的返回信息，和 @ApiImplicitParam 注解配合使用；@ApiImplicitParam 用來描述具體某一個(gè)參數(shù)的信息，包括參數(shù)的名稱、類型、限制等信息。
@ApiOperation(
value = "save 消息列表",
notes = "save 完整的消息內(nèi)容列表",
produces="application/www-xxxxx, application/xml",
consumes="application/json, application/xml",
response = List.class
)
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "消息 ID", required = true, dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "age", value = "年齡", required = true, dataType = "int", paramType = "query"),
})
屬性名稱 備注
name 接收參數(shù)名
value 接收參數(shù)的意義描述
required 參數(shù)是否必填值為 true 或者 false
dataType 參數(shù)的數(shù)據(jù)類型只作為標(biāo)志說明，并沒有實(shí)際驗(yàn)證
paramType 查詢參數(shù)類型，其值：
path 以地址的形式提交數(shù)據(jù)
query 直接跟參數(shù)完成自動(dòng)映射賦
body 以流的形式提交，僅支持 POST
header 參數(shù)在 request headers 里邊提交
form 以 form 表單的形式提交 僅支持 POST
defaultValue 默認(rèn)值
@ApiResponses 和 @ApiResponse 的使用
@ApiResponses 主要封裝方法的返回信息和 @ApiResponse 配置起來使用，@ApiResponse 定義返回的具體信息包括返回碼、返回信息等。
@ApiOperation(value = "修改用戶", notes = "根據(jù)參數(shù)修改用戶")
@ApiResponses({
@ApiResponse(code = 100, message = "請(qǐng)求參數(shù)有誤"),
@ApiResponse(code = 101, message = "未授權(quán)"),
@ApiResponse(code = 103, message = "禁止訪問"),
@ApiResponse(code = 104, message = "請(qǐng)求路徑不存在"),
@ApiResponse(code = 200, message = "服務(wù)器內(nèi)部錯(cuò)誤")
})
@PutMapping(value = "updateUser")
public ReturnModle updateUser(@Valid User user, BindingResult result) {
return null;
}
屬性名稱 備注
code http 的狀態(tài)碼
message 描述
response 默認(rèn)響應(yīng)類 Void
reference 參考
responseHeaders 封裝返回信息
responseContainer 字符串
@ApiModel 和 @ApiModelProperty 的使用
在實(shí)際的項(xiàng)目中我們常常會(huì)封裝一個(gè)對(duì)象作為返回值，@ApiModel 就是負(fù)責(zé)描述對(duì)象的信息，@ApiModelProperty 負(fù)責(zé)描述對(duì)象中屬性的相關(guān)內(nèi)容。
@ApiOperation(value = "修改用戶", notes = "根據(jù)參數(shù)修改用戶")
@PatchMapping(value = "updateUser")
public ReturnModle<User> updateUser(@Valid User user, BindingResult result) {
return new ReturnModle(0,"成功",user);
}
總結(jié)
通過 "絲襪哥"我們可以構(gòu)建一個(gè)很強(qiáng)大的restful api 文檔
我們既可以在管理界面測(cè)試也可以看到相應(yīng)的數(shù)據(jù)，也可以通過命令方式去測(cè)試。
測(cè)試
點(diǎn)擊 try it out 進(jìn)行測(cè)試
響應(yīng)
