清單 6. 給 Controller 添加描述信息

@Api(tags = "用戶相關接口", description = "提供用戶相關的 Rest API") public class UserController

@Api: 可設置對控制器的描述。

表 1. @Api 主要屬性

注解屬性 類型 描述
tags String[] 控制器標簽。
description String 控制器描述（該字段被申明為過期）。
二、通過在接口方法上增加 @ApiOperation 注解來展開對接口的描述，當然這個注解還可以指定很多內容，我們在下面的相關注解說明章節中詳細解釋。

清單 7. 給接口添加描述信息

@ApiOperation("新增用戶接口") @PostMapping("/add") public boolean addUser(@RequestBody User user) {return false; }

@ApiOperation: 可設置對接口的描述。
表 2. @ApiOperation 主要屬性

注解屬性 類型 描述
value String 接口說明。
notes String 接口發布說明。
tags Stirng[] 標簽。
response Class<?> 接口返回類型。
httpMethod String 接口請求方式。
@ApiIgnore: Swagger 文檔不會顯示擁有該注解的接口。
@ApiImplicitParams: 用于描述接口的非對象參數集。
@ApiImplicitParam: 用于描述接口的非對象參數，一般與 @ApiImplicitParams 組合使用。
表 3. @ApiImplicitParam 主要屬性

注解屬性 描述
paramType 查詢參數類型，實際上就是參數放在那里。取值：
path：以地址的形式提交數據，根據 id 查詢用戶的接口就是這種形式傳參。
query：Query string 的方式傳參。
header：以流的形式提交。
form：以 Form 表單的形式提交。
dataType 參數的數據類型。取值：
Long
String
name 參數名字。
value 參數意義的描述。
required 是否必填。取值：
true：必填參數。
false：非必填參數。
三、實體描述，我們可以通過 @ApiModel 和 @ApiModelProperty 注解來對我們 API 中所涉及到的對象做描述。

清單 8. 給實體類添加描述信息

@ApiModel("用戶實體") public class User {@ApiModelProperty("用戶 id") private int id; }

@ApiModel: 可設置接口相關實體的描述。
@ApiModelProperty: 可設置實體屬性的相關描述。
表 4. @ApiModelProperty 主要屬性

注解屬性 類型 描述
value String 字段說明。
name String 重寫字段名稱。
dataType Stirng 重寫字段類型。
required boolean 是否必填。
example Stirng 舉例說明。
hidden boolean 是否在文檔中隱藏該字段。
allowEmptyValue boolean 是否允許為空。
allowableValues String 該字段允許的值，當我們 API 的某個參數為枚舉類型時，使用這個屬性就可以清楚地告訴 API 使用者該參數所能允許傳入的值。
四、文檔信息配置，Swagger 還支持設置一些文檔的版本號、聯系人郵箱、網站、版權、開源協議等等信息，但與上面幾條不同的是這些信息不是通過注解配置，而是通過創建一個 ApiInfo 對象，并且使用 Docket.appInfo() 方法來設置，我們在 SwaggerConfig.java 類中新增如下內容即可。

清單 9. 配置文檔信息

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfo("Spring Boot 項目集成 Swagger 實例文檔","我的博客網站：https://itweknow.cn，歡迎大家訪問。","API V1.0","Terms of service",new Contact("名字想好沒", "https://itweknow.cn", "gancy.programmer@gmail.com"),"Apache", "http://www.apache.org/", Collections.emptyList()); }

四、過濾不需要掃描的包：

有些時候我們并不是希望所有的 Rest API 都呈現在文檔上，這種情況下 Swagger2 提供給我們了兩種方式配置，一種是基于 @ApiIgnore 注解，另一種是在 Docket 上增加篩選。

@ApiIgnore 注解。
如果想在文檔中屏蔽掉刪除用戶的接口（user/delete），那么只需要在刪除用戶的方法上加上 @ApiIgnore 即可。

清單 10. @ApiIgnore 使用實例

@ApiIgnore public boolean delete(@PathVariable("id") int id)

在 Docket 上增加篩選。Docket 類提供了 apis() 和 paths()兩 個方法來幫助我們在不同級別上過濾接口：
apis()：這種方式我們可以通過指定包名的方式，讓 Swagger 只去某些包下面掃描。
paths()：這種方式可以通過篩選 API 的 url 來進行過濾。
在集成 Swagger2 的章節中我們這兩個方法指定的都是掃描所有，沒有指定任何過濾條件。如果我們在我們修改之前定義的 Docket 對象的 apis() 方法和 paths() 方法為下面的內容，那么接口文檔將只會展示 /user/add 和 /user/find/{id} 兩個接口。

清單 11. 使用 Docket 配置接口篩選

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller")) .paths(Predicates.or(PathSelectors.ant("/user/add"),PathSelectors.ant("/user/find/*")))

五、自定義響應消息

Swagger 允許我們通過 Docket 的 globalResponseMessage() 方法全局覆蓋 HTTP 方法的響應消息，但是首先我們得通過 Docket 的 useDefaultResponseMessages 方法告訴 Swagger 不使用默認的 HTTP 響應消息，假設我們現在需要覆蓋所有 GET 方法的 500 和 403 錯誤的響應消息，我們只需要在 SwaggerConfig.java 類中的 Docket Bean 下添加如下內容：

清單 12. 自定義響應消息

.useDefaultResponseMessages(false) .globalResponseMessage(RequestMethod.GET, newArrayList( new ResponseMessageBuilder().code(500).message("服務器發生異常").responseModel(new ModelRef("Error")).build(),new ResponseMessageBuilder().code(403).message("資源不可用").build() ));

添加如上面的代碼后，如下圖所示，您會發現在 SwaggerUI 頁面展示的所有 GET 類型請求的 403 以及 500 錯誤的響應消息都變成了我們自定義的內容。

總結

以上是生活随笔為你收集整理的Swagger的描述注释配置详解的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。