SpringBoot集成 Swagger

Spring Boot 集成 Swagger 在线接口文档

1、Swagger 简介

1.1 解决的问题

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口，所以 API 文档变成了前后端开

发人员联系的纽带，变得越来越重要。

那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

1.2 Swagger 官方

打开 Swagger 官网为 https://swagger.io/

主要掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档。

2、Swagger 的 maven 依赖

使用 Swagger 工具，必须要导入 maven 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3、Swagger 配置

使用 Swagger 需要进行配置，Spring Boot 中对 Swagger 的配置非常方便，新建一个配置类，Swagger 的配置类上除了添加必要的@Configuration 注解外，还需要添加@EnableOpenApi 注解。

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
            // 是否关闭在线文档，生产环境关闭
            .enable(true)
             // 指定构建 api 文档的详细信息的方法
            .apiInfo(apiInfo())
// 指定要生成 api 接口的包路径，这里把 action 作为包路径，生成 controller 中的所有接口 
            .apis(RequestHandlerSelectors.basePackage("com.ma.action"))
            .select() 
            //只 有 在 方 法接口上添加了 ApiOperation 注解
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any()).build().globalResponses(HttpMethod.GET, 
getGlobalResponseMessage())
            .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }
}

// 生成摘要信息
private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("接口文档") //设置页面标题
    .description("说明信息") 设置接口描述
    .contact(new Contact("yangyang", "http://baidu.com", "yang@yang.com")) //设置联系方式
    .version("1.0") //设置版本
    .build(); //构建
}

在该配置类中已经使用注释详细解释了每个方法的作用了。到此已经配置好 Swagger 了。现在可以测试一下

配置有没有生效，启动项目，在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的

接口页面，说明 Swagger 集成成功。

对照 Swagger 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握Swagger 中的配置了，也可以看出，其实 Swagger 配置很简单。

有可能在配置 Swagger 时关不掉，是因为浏览器缓存引起的，清空一下浏览器缓存即可解决问题。

相关配置

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4、Swagger 的使用

已经配置好了 Swagger，并且也启动测试了一下，功能正常，下面可以开始使用 Swagger，重点要掌握 Swagger中常用的注解，分别在实体类上、Controller 类上以及 Controller 中的方法上，最后查看 Swagger 如何在页面上呈现在线接口文档的，并且结合 Controller 中的方法在接口中测试一下数据。

4.1 实体类注解

定义 User 实体类，这里主要介绍 Swagger 中的@ApiModel 和@ApiModelProperty 注解。

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
    // 省略 set 和 get 方法
}

其中@ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。

@ApiModelProperty 注解用于类中属性，表示对 model 属性的说明或者数据操作更改。

4.2 Controller 类中相关注解

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
        // 模拟数据库中根据 id 获取 User 信息
        User user = new User(id, "小灰灰", "123456");
        return new JsonResult(user);
    }
}

1、@Api 注解用于类上，表示标识这个类是 swagger 的资源。

2、@ApiOperation 注解用于方法，表示一个 http 请求的操作。

3、@ApiParam 注解用于参数上，用来标明参数信息。

在浏览器中可以看出 Swagger 页面对该接口的信息展示的非常全面，每个注解的作用以及展示的地方注意对应位置，通过页面即可知道该接口的所有信息，那么直接在线测试一下该接口返回的信息，输入 id 为 1，看一下返回数据。

可以看出，直接在页面返回了 json 格式的数据，开发人员可以直接使用该在线接口来测试数据的正确与否，非常方便。

@PostMapping("/insert")
@ApiOperation(value = "添加用户信息")
public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
    // 处理添加逻辑
    return new JsonResult<>();
}

重启项目，然后在浏览器中输入 localhost:8080/swagger-ui.html 看效果

5、总结

主要详细分析 Swagger 的优点以及 Spring Boot 集成 Swagger，包括配置，涉及到了实体类和接口类以及如何使用。最后通过页面测试，可以体验 Swagger 的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。

完整代码实现

1、pom.xml文件：

<?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>
    <groupId>com.ma</groupId>
    <artifactId>swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-boot.version>2.6.13</spring-boot.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>4.2.2</version>
        </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-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <configuration>
                    <mainClass>com.ma.SwaggerApplication</mainClass>
                    <skip>true</skip>
                </configuration>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

2、application.properties文件

# 应用服务 WEB 访问端口
server.port=8080

# swagger相关的一个路径匹配规则的配置，如果不进行配置则无法访问到swagger的页面
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

3、SwaggerApplication文件：

package com.ma;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

4、创建一个action的包在包内创建HelloController.java文件：

package com.ma.action;

import com.ma.domain.JsonResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api(tags="测试控制器")
@RestController
@RequestMapping("/test")
public class HelloController {
    @ApiOperation("问候语测试")
    @GetMapping("/hello")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "666666")
    })
    public JsonResult hello(@ApiParam("用户名称") @RequestParam(value="username",required =true) String name){
        String res = "hello" + name + "!";
        return JsonResult.success("处理完毕",res);
    }
}

5、创建一个conf的包在包内创建Swagger3Config.java文件：

package com.ma.conf;

import io.swagger.models.HttpMethod;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@EnableOpenApi
@Configuration
public class Swagger3Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * swagger测试地址：http://localhost:8080/swagger-ui/index.html#/
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
                .enable(true)// 是否关闭在线文档，生产环境关闭
                .apiInfo(apiInfo())  // 指定构建api文档的详细信息的方法
                .select()  // 指定要生成api接口的包路径，这里把action作为包路径，生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.ma.action"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
                .paths(PathSelectors.any()).build()
                //针对应用的全局响应消息配置
//                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
//                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                ;
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档") //设置页面标题
                .description("说明信息")  //设置接口描述
                .contact(new Contact("mayang", "http://baidu.com", "ma@ma.com")) //设置联系方式
                .version("1.0") //设置版本
                .build();  //构建
    }
}

6、创建一个domain的包在包内创建JsonResult.java文件：

package com.ma.domain;

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

import java.io.Serializable;

@Data
@ApiModel("针对前端的响应数据格式规范")
public class JsonResult implements Serializable {
    @ApiModelProperty("是否处理成功，布尔类型数据")
    private Boolean success;
    @ApiModelProperty("响应消息信息，字符串类型")
    private String message;
    @ApiModelProperty("响应数据，对象类型")
    private Object data;

    public static JsonResult success(String message, Object data) {
        JsonResult res=new JsonResult();
        res.setMessage(message);
        res.setSuccess(true);
        res.setData(data);
        return res;
    }
}

7、启动程序后可以通过访问地址http://localhost:8080/swagger-ui/index.html来对swagger网站进行操作