SpringBoot 整合 Swagger 2

在前後端分離開發中，爲了減少與其他團隊的溝通成本，一般構建一份 RESTful API 文檔來描述所有的接口信息，但是這種做法有很大的弊端：

• 接口衆多，編寫 RESTful API 文檔工作量巨大，因爲 RESTful API 文檔不僅要包含接口的基本信息，如接口地址、接口請求參數以及接口返回值等，還要包含 HTTP 請求類型、 HTTP 請求頭、請求參數類型、返回值類型、所需權限等。
• 維護不方便，一旦接口發生變化，就要修改文檔。
• 接口測試不方便，一般只能藉助第三方工具（如 Postman ）來測試。

Swagger 2 是一個開源軟件框架，可以幫助開發人員設計、構建、記錄和使用 RESTful Web 服務，它將代碼和文檔融爲一體，可以完美解決上述問題，使開發人員將大部分精力集中到業務中，而不是繁雜瑣碎的文檔中。

整合步驟

添加 Swagger 2 相關依賴：

<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>

創建 Swagger 2 的配置類：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("xyz.ther.boot.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                .description("示例接口文檔")
                .contact(new Contact("Ther", "https://github/siriusol", "[email protected]"))
                .version("v1.0")
                .title("API測試文檔")
                .license("Apache2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build());
    }
}

代碼解釋：

• 首先通過 @EnableSwagger2 註解開啓 Swagger 2 ，然後最主要的是配置一個 Docket。
• 通過 apis 方法配置要掃描的 controller 位置，通過 paths 方法配置路徑。
• 在 apiInfo 中構建文檔的基本信息，例如描述、聯繫人信息、版本、標題等。

Swagger 2 配置完成後，接下來開發接口，代碼如下：

實體類：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用戶實體類", description = "用戶信息描述類")
public class User {
    @ApiModelProperty(value = "用戶名")
    private String username;

    @ApiModelProperty(value = "用戶地址")
    private String address;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

Controller 類：

import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api(tags = "用戶數據接口")
public class UserController {
    @Autowired
    UserService userService;

    @ApiOperation(value = "查詢用戶", notes = "根據 id 查詢用戶")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用戶 id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "userId=" + id;
    }

    @ApiResponses({
    @ApiResponse(code = 200, message ="刪除成功"),
    @ApiResponse(code = 500, message = "刪除失敗")})
    @ApiOperation(value = "刪除用戶",  notes = "通過 id 刪除用戶")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserByid(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "添加用戶", notes ="傳入用戶名和地址添加一個用戶")
    @ApiImplicitParams({
    @ApiImplicitParam(paramType = "query", name = "username", value = "用戶名", required = true, defaultValue = "Ther"),
    @ApiImplicitParam(paramType = "query", name = "address", value = "用戶地址", required = true, defaultValue = "China")})
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String address) {
        return username + ":" + address;
    }

    @ApiOperation(value = "修改用戶", notes ="傳入用戶信息修改用戶")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user) {
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ignoreMethod() {}
}

代碼解釋：

• @Api 註解用在類上，用來描述整個 Controller 信息。
• @ApiOperation 註解用在方法上，用來描述一個方法的基本信息，value 是對方法作用的一個簡短描述，notes 則用來備註該方法的詳細作用。
• @ApilmplicitParam 註解用在方法上，用來描述方法的參數， paramType 是指方法參數的類型，可選值有 path (參數獲取方式 ＠PathVariable)、query (參數獲取方式 ＠RequestParam)、header (參數獲取方式 RequestHeader)、body 以及 form；name 表示參數名稱，和參數變量對應；value 是參數的描述信息； required 表示該字段是否必填； defaultValue 表示該字段的默認值。注意，這裏的 required 和 defaultValue 等字段只是文檔上的約束描述，並不能真正約束接口，約束接口還需要在 @RequestParam 中添加相關屬性。如果方法有多個參數，可以將多個參數 @ApilmplicitParam 註解放到 @ApilmplicitParams 中。
• @ApiResponse 註解是對響應結果的描述，code 表示響應碼，message 表示響應的描述信息， 若有多個 @ApiResponse，則放在一個 ＠ApiResponses 中。
• updateUser 方法中，使用 ＠RequestBody 註解來接收數據，此時可以通過 @ApiModel 註解和 @ApiModelProperty 註解配置 User 的描述信息。
• @Apilgnore 註解表示不對某個接口生成文檔。

啓動 Spring Boot 項目，在瀏覽器中輸入：http://localhost:8080/swagger-ui.html 即可看到接口文檔。