Spring Boot 集成 Swagger 構建接口文檔

在應用開發過程當中常常須要對其餘應用或者客戶端提供 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 依賴，項目依賴以下所示：

<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <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>

加入配置

接下來在 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", "wupx@qq.com"))
                .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<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "獲取用戶列表", notes = "獲取用戶列表")
    public List<User> 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/... 的 interface-doc 目錄下。

最好的關係就是互相成就，你們的在看、轉發、留言三連就是我創做的最大動力。

參考

http://swagger.io

https://github.com/wupeixuan/...

《Spring Boot 2 實戰之旅》