在應用開發過程中經常需要對其他應用或者客戶端提供 RESTful API 介面，尤其是在版本快速迭代的開發過程中，**修改介面的同時還需要同步修改對應的介面文件**，這使我們總是做著重複的工作，並且如果**忘記修改介面文件**，就可能造成不必要的麻煩。 為了解決這些問題，Swagger 就孕育而生了，那讓我們先簡單瞭解下。 ## Swagger 簡介 Swagger 是一個規範和完整的框架，用於**生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務**。 總體目標是使客戶端和檔案系統作為伺服器，以同樣的速度來更新。檔案的方法、引數和模型緊密整合到伺服器端的程式碼中，允許 API 始終保持同步。 下面我們在 Spring Boot 中整合 Swagger 來構建強大的介面文件。 ## Spring Boot 整合 Swagger Spring Boot 整合 Swagger 主要分為以下三步： 1. 加入 Swagger 依賴 2. 加入 Swagger 文件配置 3. 使用 Swagger 註解編寫 API 文件 ### 加入依賴 首先建立一個專案，在專案中加入 Swagger 依賴，專案依賴如下所示： ``` org.springframework.boot spring-boot-starter-web io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2 ``` ### 加入配置 接下來在 `config` 包下建立一個 Swagger 配置類 `Swagger2Configuration`，在配置類上加入註解 `@EnableSwagger2`，表明開啟 Swagger，注入一個 Docket 類來配置一些 API 相關資訊，`apiInfo()` 方法內定義了幾個文件資訊，程式碼如下： ``` @Configuration @EnableSwagger2 public class Swagger2Configuration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // swagger 文件掃描的包 .apis(RequestHandlerSelectors.basePackage("com.wupx.interfacedoc.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("測試介面列表") .description("Swagger2 介面文件") .version("v1.0.0") .contact(new Contact("wupx", "https://www.tianheyu.top", "[email protected]")) .license("Apache License, Version 2.0") .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") .build(); } } ``` 列舉其中幾個文件資訊說明下： - title：介面文件的標題 - description：介面文件的詳細描述 - termsOfServiceUrl：一般用於存放公司的地址 - version：API 文件的版本號 - contact：維護人、維護人 URL 以及 email - license：許可證 - licenseUrl：許可證 URL ### 編寫 API 文件 在 `domain` 包下建立一個 `User` 實體類，使用 `@ApiModel` 註解表明這是一個 Swagger 返回的實體，`@ApiModelProperty` 註解表明幾個實體的屬性，程式碼如下（其中 getter/setter 省略不顯示）： ``` @ApiModel(value = "使用者", description = "使用者實體類") public class User { @ApiModelProperty(value = "使用者 id", hidden = true) private Long id; @ApiModelProperty(value = "使用者姓名") private String name; @ApiModelProperty(value = "使用者年齡") private String age; // getter/setter } ``` 最後，在 `controller` 包下建立一個 `UserController` 類，提供使用者 API 介面（未使用資料庫），程式碼如下： ``` @RestController @RequestMapping("/users") @Api(tags = "使用者管理介面") public class UserController { Map users = Collections.synchronizedMap(new HashMap<>()); @GetMapping("/") @ApiOperation(value = "獲取使用者列表", notes = "獲取使用者列表") public List getUserList() { return new ArrayList<>(users.values()); } @PostMapping("/") @ApiOperation(value = "建立使用者") public String addUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @GetMapping("/{id}") @ApiOperation(value = "獲取指定 id 的使用者") @ApiImplicitParam(name = "id", value = "使用者 id", paramType = "query", dataTypeClass = Long.class, defaultValue = "999", required = true) public User getUserById(@PathVariable Long id) { return users.get(id); } @PutMapping("/{id}") @ApiOperation(value = "根據 id 更新使用者") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "使用者 id", defaultValue = "1"), @ApiImplicitParam(name = "name", value = "使用者姓名", defaultValue = "wupx"), @ApiImplicitParam(name = "age", value = "使用者年齡", defaultValue = "18") }) public User updateUserById(@PathVariable Long id, @RequestParam String name, @RequestParam Integer age) { User user = users.get(id); user.setName(name); user.setAge(age); return user; } @DeleteMapping("/{id}") @ApiOperation(value = "刪除使用者", notes = "根據 id 刪除使用者") @ApiImplicitParam(name = "id", value = "使用者 id", dataTypeClass = Long.class, required = true) public String deleteUserById(@PathVariable Long id) { users.remove(id); return "success"; } } ``` 啟動專案，訪問 `http://localhost:8080/swagger-ui.html`，可以看到我們定義的文件已經在 Swagger 頁面上顯示了，如下圖所示：  到此為止，我們就完成了 Spring Boot 與 Swagger 的整合。 同時 Swagger 除了**介面文件功能**外，還提供了**介面除錯**功能，以建立使用者介面為例，單擊建立使用者介面，可以看到介面定義的**引數、返回值、響應碼**等，單擊 `Try it out` 按鈕，然後點選 `Execute` 就可以發起呼叫請求、建立使用者，如下圖所示：  ## 註解介紹 由於 Swagger 2 提供了非常多的註解供開發使用，這裡列舉一些比較常用的註解。 ### @Api `@Api` 用在介面文件資源類上，用於標記當前類為 Swagger 的文件資源，其中含有幾個常用屬性： - value：定義當前介面文件的名稱。 - description：用於定義當前介面文件的介紹。 - tag：可以使用多個名稱來定義文件，但若同時存在 tag 屬性和 value 屬性，則 value 屬性會失效。 - hidden：如果值為 true，就會隱藏文件。 ### @ApiOperation `@ApiOperation` 用在介面文件的方法上，主要用來註解介面，其中包含幾個常用屬性： - value：對API的簡短描述。 - note：API的有關細節描述。 - esponse：介面的返回型別（注意：這裡不是返回實際響應，而是返回物件的實際結果）。 - hidden：如果值為 true，就會在文件中隱藏。 ### @ApiResponse、@ApiResponses `@ApiResponses` 和 @`ApiResponse` 二者配合使用返回 HTTP 狀態碼。`@ApiResponses` 的 value 值是 `@ApiResponse` 的集合，多個 `@ApiResponse` 用逗號分隔，其中 `@ApiResponse` 包含的屬性如下： - code：HTTP狀態碼。 - message：HTTP狀態資訊。 - responseHeaders：HTTP 響應頭。 ### @ApiParam `@ApiParam` 用於方法的引數，其中包含以下幾個常用屬性： - name：引數的名稱。 - value：引數值。 - required：如果值為 true，就是必傳欄位。 - defaultValue：引數的預設值。 - type：引數的型別。 - hidden：如果值為 true，就隱藏這個引數。 ### @ApiImplicitParam、@ApiImplicitParams 二者配合使用在 API 方法上，`@ApiImplicitParams` 的子集是 `@ApiImplicitParam` 註解，其中 `@ApiImplicitParam` 註解包含以下幾個引數： - name：引數的名稱。 - value：引數值。 - required：如果值為 true，就是必傳欄位。 - defaultValue：引數的預設值。 - dataType：資料的型別。 - hidden：如果值為 true，就隱藏這個引數。 - allowMultiple：是否允許重複。 ### @ResponseHeader API 文件的響應頭，如果需要設定響應頭，就將 `@ResponseHeader` 設定到 `@ApiResponse` 的 `responseHeaders` 引數中。`@ResponseHeader` 提供了以下幾個引數： - name：響應頭名稱。 - description：響應頭備註。 ### @ApiModel 設定 API 響應的實體類，用作 API 返回物件。`@ApiModel` 提供了以下幾個引數： - value：實體類名稱。 - description：實體類描述。 - subTypes：子類的型別。 ### @ApiModelProperty 設定 API 響應實體的屬性，其中包含以下幾個引數： - name：屬性名稱。 - value：屬性值。 - notes：屬性的註釋。 - dataType：資料的型別。 - required：如果值為 true，就必須傳入這個欄位。 - hidden：如果值為 true，就隱藏這個欄位。 - readOnly：如果值為 true，欄位就是隻讀的。 - allowEmptyValue：如果為 true，就允許為空值。 到此為止，我們就介紹完了 Swagger 提供的主要註解。 # 總結 Swagger 可以輕鬆地整合到 Spring Boot 中構建出強大的 RESTful API 文件，可以減少我們編寫介面文件的工作量，同時介面的說明內容也整合入程式碼中，可以讓我們在修改程式碼邏輯的同時方便的修改介面文件說明，另外 Swagger 也提供了頁面測試功能來除錯每個 RESTful API。 如果專案中還未使用，不防嘗試一下，會發現效率會提升不少。 本文的完整程式碼在 https://github.com/wupeixuan/SpringBoot-Learn 的 `interface-doc` 目錄下。 **最好的關係就是互相成就**，大家的**在看、轉發、留言**三連就是我創作的最大動力。 > 參考 > > http://swagger.io > > https://github.com/wupeixuan/SpringBoot-Learn > > 《Spring Boot 2 實戰之旅》