Spring Boot從入門到精通（十一）整合Swagger框架，實現自動生成介面文件

yoodb發表於2021-08-08
Spring BootSwagger框架

Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。Swagger 是一組開源專案，其中主要要專案如下：

Swagger-tools：提供各種與Swagger進行整合和互動的工具。例如模式檢驗

Swagger 1.2文件轉換成Swagger 2.0文件等功能。

Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行整合。
Swagger-js: 用於JavaScript的Swagger實現。

Swagger-node-express: Swagger模組，用於node.js的Express web應用框架。

Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger相容API動態生成優雅文件。

Swagger-codegen：一個模板驅動引擎，通過分析使用者Swagger資源宣告以各種語言生成客戶端程式碼。

在專案開發中，Swagger 可以根據不同的業務程式碼實現自動生成API文件，提供給前端呼叫方線上測試，且自動顯示返回採納數JSON格式的字串，從而節省後端與前端人員的溝通與除錯成本。

Swagger 有一個最大的劣勢就是“侵入性”模式，配置資訊必須在具體程式碼中來實現，在下面的搭建過程中，大家就會明白說的是什麼意思了。
新建Maven專案，在pom.xml檔案引入依賴

方式一：使用官方推薦依賴，在pom.xml檔案中新增Swagger包依賴，具體配置資訊如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-study-demo07</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>springboot-study-demo07</name>
    <description>Demo project for Spring Boot</description>
 
    <properties>
        <java.version>1.8</java.version>
    </properties>
 
    <dependencies>
        <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>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
 
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
 
</project>

方式二：使用第三方包引入依賴，在pom.xml檔案中新增第三方swagger包依賴，具體配置資訊如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-study-demo07</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>springboot-study-demo07</name>
    <description>Demo project for Spring Boot</description>
 
    <properties>
        <java.version>1.8</java.version>
    </properties>
 
    <dependencies>
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.1.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
 
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

自定義Swagger配置資訊

新建Swagger配置類，需要注意的是“Swagger scan base package”，這是掃描註解的配置，即API介面位置，對前端呼叫方提供服務介面的位置。

package com.yoodb.study.demo07.config;
 
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API介面文件")
                .description("“Java精選”微信公眾號資訊")
                .version("1.0.0")
                .build();
    }
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yoodb.study.demo07")) //API介面所在的包位置
                .paths(PathSelectors.any())
                .build();
    }
 
}

新建Controller類檔案

新建HelloWorldController類檔案，建立GET和POST兩種請求方法，以介面方式提供給前端呼叫，具體程式碼如下：

package com.yoodb.study.demo07;
 
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
 
@Api(value = "hello")
@RestController
public class HelloWorldController {
    /**
     * 根據公眾號名稱獲取詳細描述資訊
     * @return
     */
    @ApiOperation(value = "獲取公眾號詳細描述資訊", notes = "根據公眾號名稱獲取詳細描述資訊")
    @ApiImplicitParam(name = "name", value = "公眾號名稱", required = true, dataType = "String", paramType = "path")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful — 請求已完成"),
            @ApiResponse(code = 400, message = "請求語法問題或無法滿足請求"),
            @ApiResponse(code = 401, message = "Unauthorized，未授權訪問"),
            @ApiResponse(code = 404, message = "伺服器找不到資源；檔案不存在"),
            @ApiResponse(code = 500, message = "伺服器不能完成請求")}
    )
    @GetMapping("getName/{name}")
    public String getName(@PathVariable(value = "name") String name) {
        return "關注微信公眾號“" +name+ "”(w_z90110)，" +
                "Spring Boot系列文章持續更新中，" +
                "帶你從入門到精通，玩轉Spring Boot框架。";
    }
 
    /**
     * 根據公眾號編號獲取詳細描述資訊
     * @return
     */
    @ApiOperation(value = "獲取公眾號詳細描述資訊", notes = "根據公眾號編號獲取詳細描述資訊")
    @ApiImplicitParam(name = "id", value = "公眾號編號", required = true, dataType = "String", paramType = "path")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful — 請求已完成"),
            @ApiResponse(code = 400, message = "請求語法問題或無法滿足請求"),
            @ApiResponse(code = 401, message = "Unauthorized，未授權訪問"),
            @ApiResponse(code = 404, message = "伺服器找不到資源；檔案不存在"),
            @ApiResponse(code = 500, message = "伺服器不能完成請求")}
    )
    @PostMapping("getId/{id}")
    public String getId(@PathVariable(value = "id") String id) {
        return "關注微信公眾號“Java精選”(" +id+ ")，" +
                "Spring Boot系列文章持續更新中，" +
                "帶你從入門到精通，玩轉Spring Boot框架。";
    }
}

設定訪問API文件

在application.yml配置檔案中，增加配置資訊如下：

springfox.documentation.swagger.v2.path: /api-docs

此配置資訊是指以json串的形式訪問request mapping，可以自定義，防止與自身程式碼衝突，使用位置參考截圖所示（專案啟動後通過地址訪問該服務）：

在這裡插入圖片描述

新增啟動類檔案

新建啟動類檔案，使用@EnableSwagger2註解，具體程式碼如下：

package com.yoodb.study.demo07;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@SpringBootApplication
@EnableSwagger2
public class SpringbootStudyDemo07Application {
 
    public static void main(String[] args) {
        SpringApplication.run(SpringbootStudyDemo07Application.class, args);
 
    }
 
}

完成上述程式碼配置後，啟動Spring Boot程式，訪問swagger地址：

http://localhost:8080/swagger-ui.html

在這裡插入圖片描述
在這裡插入圖片描述在這裡插入圖片描述
Swagger常用註解

@Api：用在類上，說明該類的作用。以標記一個Controller類做為swagger文件資源，如果目前在找工作或者以後要跳槽考慮，可以搜尋微信小程式“Java精選面試題”，內涵3000道初中高階面試題以及幾千到選擇題，選擇題內涵答案解析，使用方式參考如下：

@Api(value = "hello")
@ApiOperation：用在方法上，說明方法的作用，Url資源的定義，使用方式參考如下：

@ApiOperation(value = "獲取公眾號詳細描述資訊", notes = "根據公眾號名稱獲取詳細描述資訊")

@ApiImplicitParams : 用在方法上包含一組引數說明。

@ApiImplicitParam：用來註解來給方法入參增加說明。使用方式參考如下：

@ApiImplicitParam(name = "name", value = "公眾號名稱", required = true, dataType = "String", paramType = "path")

name：引數名
dataType：引數型別
required：引數是否必須傳
value：說明引數的意思
defaultValue：引數的預設值
paramType：表示引數放在什麼位置
paramType引數值包含如下：
header->請求引數的獲取：@RequestHeader(程式碼中接收註解)
query->請求引數的獲取：@RequestParam(程式碼中接收註解)
path（用於restful介面）–>請求引數的獲取：@PathVariable(程式碼中接收註解)
body->請求引數的獲取：@RequestBody(程式碼中接收註解)
form->（不常用）

@ApiResponses：用於方法上，表示一組響應。

@ApiResponse：在@ApiResponses註解內，一般用於表達一個錯誤的響應資訊，使用方式參考如下：

@ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful — 請求已完成"),
            @ApiResponse(code = 400, message = "請求語法問題或無法滿足請求"),
            @ApiResponse(code = 401, message = "Unauthorized，未授權訪問"),
            @ApiResponse(code = 404, message = "伺服器找不到資源；檔案不存在"),
            @ApiResponse(code = 500, message = "伺服器不能完成請求")}
    )

code->數字，提示狀態碼400
message->資訊
response->丟擲異常的類

@ApiModel：用於類，描述一個Model的資訊，一般用在請求引數無法使用，表示對類進行說明，用於引數用實體類接收。

@ApiModelProperty：用於方法，描述一個model的屬性，表示對model屬性的說明或者資料操作更改。

本文篇文章的專案原始碼（springboot-study-demo07）地址：

https://github.com/yoodb/springboot

相關文章