SpringBoot2.0實戰 | 第十一章：整合Swagger2自動生成API文檔

相關知識

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger官網：https://swagger.io

常用註解：

• @Api 用於類，表示標識這個類是swagger的資源
• @ApiOperation 用於方法，表示一個http請求的操作
• @ApiParam 用於方法，參數，字段說明，表示對參數的添加元數據（說明或是否必填等）
• @ApiModel 用於類，表示對類進行說明，用於參數用實體類接收
• @ApiModelProperty 用於方法，字段，表示對model屬性的說明或者數據操作更改
• @ApiIgnore 用於類，方法，方法參數，表示這個方法或者類被忽略
• @ApiImplicitParam 用於方法，表示單獨的請求參數
• @ApiImplicitParams 用於方法，包含多個 @ApiImplicitParam

目標

整合 Swagger2 實現自動生成接口文檔

操作步驟

添加依賴

引入 Spring Boot Starter 父工程

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.5.RELEASE</version>
</parent>

添加 Swagger2 的依賴

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

整體依賴如下

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-tomcat</artifactId>
            </exclusion>
        </exclusions>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-undertow</artifactId>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>

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

註冊 Swagger2

/**
 * @Configuration 用於啓動自動加載
 * @EnableSwagger2 用於開啓 Swagger
 */
@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {

    /**
     * 創建API應用
     * apiInfo() 增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
     * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 控制暴露出去的路徑下的實例
                // 如果某個接口不想暴露,可以使用以下註解
                // @ApiIgnore 這樣,該接口就不會暴露在 swagger2 的頁面下
                .apis(RequestHandlerSelectors.basePackage("com.mhkj.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 創建該API的基本信息（這些基本信息會展現在文檔頁面中）
     * 訪問地址：http://項目實際地址/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文檔")
                .version("1.0.0-SNAPSHOT")
                .build();
    }

}

編碼

1. Controller 層代碼

爲接口添加 Swagger 註解

@RestController
@Slf4j
@Api("用戶管理")
public class UserController {

    @ApiOperation(value = "用戶註冊", notes = "用戶註冊")
    @PostMapping("/register")
    public UserBO register(@RequestBody @ApiParam(name = "註冊對象", value = "JSON對象", required = true) UserBO userBO) {
        return userBO;
    }

}

2. 入參代碼

爲入參類及類中的每一個屬性添加 Swagger 註解

@Getter
@Setter
@ApiModel("用戶註冊對象")
public class UserBO {

    @ApiModelProperty(value = "手機號", required = true)
    private String mobile;

    @ApiModelProperty(value = "密碼", required = true)
    private String upwd;

}

驗證結果

訪問 http:😕/localhost:8080/swagger-ui.html，即可看到 API 文檔

源碼地址

本章源碼 : https://gitee.com/gongm_24/spring-boot-tutorial.git

結束語

Swagger 可以實時生成文檔，保證文檔的時效性，這有助於前後端聯合開發、微服務聯合開發等