Spring Boot從入門到精通（十一）集成Swagger框架，實現自動生成接口文檔

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

Spring Boot從入門到精通（十一）集成Swagger框架，實現自動生成接口文檔

原來阿里字節大廠程序員的簡歷長這樣！

最新2022年Docker面試題高級面試題及附答案解析

這樣 PDF 的技術簡歷，HR根本不想看，談何到面試官手中？

Spring 官宣發佈 Spring Boot 3.0 第一個里程碑 M1，從 Java 8 提升到 Java 17！

爲什麼 MySQL 唯一索引會導致死鎖，“有心殺賊，無力迴天”？

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結