SpringBoot 整合 Swagger2 详细教程
|
Java

1410 字
|
14 分钟

在前后端分离的开发模式中，API 文档的编写、维护和调试是开发过程中的重要环节。手动编写接口文档效率低、易滞后、更新不及时，而 Swagger2 可以自动根据项目代码生成标准化的 RESTful API 文档，支持在线查看接口、调试接口、查看参数和返回值，极大提升前后端协作效率。

本文将手把手教大家完成 SpringBoot 整合 Swagger2 的完整配置，包含依赖引入、配置类编写、注解使用、项目测试及常见问题解决方案。

一、环境准备

本次整合使用稳定适配版本，避免版本冲突，环境配置如下：

  • SpringBoot 版本：2.7.x（兼容 Swagger2 主流版本，3.0+ 高版本 SpringBoot 需特殊适配）
  • Swagger2 版本：2.9.2（经典稳定版，无兼容 bug）
  • 开发工具：IDEA
  • 构建工具：Maven

二、引入 Maven 依赖

在 SpringBoot 项目的 pom.xml 文件中，引入 Swagger2 核心依赖和 UI 界面依赖，两个依赖缺一不可。

<!-- Swagger2 核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- Swagger2 UI 界面依赖（提供可视化文档页面） -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

引入依赖后，刷新 Maven 项目，确保依赖下载成功，无报错。

三、编写 Swagger2 配置类

在项目配置包下（如 com.xxx.config）创建 Swagger 配置类 SwaggerConfig，该类是 Swagger 生效的核心，用于配置文档信息、扫描路径、接口规则等。

package com.xxx.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 配置类
 * 开启Swagger2注解：@EnableSwagger2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用
     * Docket：Swagger核心配置类
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置文档基本信息
                .apiInfo(apiInfo())
                // 开启接口扫描
                .select()
                // 扫描指定包下的Controller接口（核心配置，修改为自己的项目controller包路径）
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                // 扫描所有路径的接口
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置API文档展示信息
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("SpringBoot整合Swagger2 接口文档")
                // 文档描述
                .description("项目前后端对接RESTful接口文档，支持在线调试")
                // 作者信息
                .contact(new Contact("开发人员", "https://xxx.com", "xxx@163.com"))
                // 项目版本
                .version("1.0.0")
                .build();
    }
}

核心注解说明：

  • @Configuration：标识该类为配置类，项目启动时自动加载
  • @EnableSwagger2：开启 Swagger2 功能，必须添加，否则文档不生效
  • RequestHandlerSelectors.basePackage：指定扫描的控制器包路径，必须修改为项目实际 Controller 路径

四、常用 Swagger2 注解使用

为了让接口文档展示更规范、信息更详细，Swagger2 提供了一系列注解，用于描述类、接口、参数、返回值。我们在 Controller 和实体类中使用注解优化文档展示效果。

4.1 实体类注解（描述参数模型）

使用 @ApiModel、@ApiModelProperty 描述实体类和字段含义。

package com.xxx.entity;

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

@Data
@ApiModel(description = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户ID", example = "1001")
    private Long id;

    @ApiModelProperty(value = "用户名", required = true, example = "testUser")
    private String username;

    @ApiModelProperty(value = "用户密码", required = true, example = "123456")
    private String password;

    @ApiModelProperty(value = "用户手机号", example = "13800138000")
    private String phone;
}

4.2 Controller 接口注解（描述接口信息）

使用 @Api、@ApiOperation、@ApiParam 描述控制器和接口。

package com.xxx.controller;

import com.xxx.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理接口")
public class UserController {

    /**
     * 查询用户列表
     */
    @GetMapping("/list")
    @ApiOperation(value = "获取用户列表", notes = "查询所有用户信息，无需参数")
    public List<User> getUserList() {
        List<User> userList = new ArrayList<>();
        User user = new User();
        user.setId(1001L);
        user.setUsername("张三");
        user.setPhone("13800138000");
        userList.add(user);
        return userList;
    }

    /**
     * 根据ID查询用户
     */
    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据ID查询用户", notes = "通过用户唯一ID获取用户详情")
    public User getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
        User user = new User();
        user.setId(id);
        user.setUsername("李四");
        return user;
    }

    /**
     * 新增用户
     */
    @PostMapping("/add")
    @ApiOperation(value = "新增用户", notes = "提交用户信息完成新增操作")
    public String addUser(@RequestBody User user) {
        return "用户新增成功";
    }
}

4.3 常用注解汇总

注解作用
@Api作用在 Controller 类上，描述模块功能
@ApiOperation作用在接口方法上，描述接口功能
@ApiParam作用在接口参数上，描述参数含义、是否必填
@ApiModel作用在实体类上，描述实体用途
@ApiModelProperty作用在实体字段上，描述字段含义、示例值、是否必填

五、启动项目测试

启动 SpringBoot 项目，确保项目无报错、正常运行。

在浏览器中输入 Swagger2 访问地址：

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

访问成功后，即可看到自动生成的可视化接口文档，包含我们配置的项目信息、用户管理接口、实体参数说明。

支持在线功能：

  • 查看所有接口的请求方式、请求路径、参数、返回值
  • 在线填写参数、发起接口请求，调试接口功能
  • 查看接口请求示例和响应示例

六、项目优化与常见问题解决

6.1 生产环境关闭 Swagger

Swagger 仅适用于开发、测试环境，生产环境需要关闭，避免暴露接口信息、占用资源。通过 @Profile 注解指定环境生效。

修改 SwaggerConfig 配置类：

@Configuration
@EnableSwagger2
// 仅在dev、test环境生效，生产prod环境关闭
@Profile({"dev","test"})
public class SwaggerConfig {
    // 原有配置不变
}

6.2 解决高版本 SpringBoot 报错问题

SpringBoot 2.6+ 版本默认路径匹配策略为 PATH_PATTERN_MATCHER，与 Swagger2 冲突，会导致项目启动报错。解决方案：在启动类中修改匹配策略。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration;
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@SpringBootApplication
public class SwaggerDemoApplication implements WebMvcConfigurer {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

    // 适配Swagger2路径匹配规则
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseSuffixPatternMatch(false);
    }
}

6.3 常见访问失败问题

  • 问题1：访问 swagger-ui.html 404
  • 解决方案：检查是否添加 @EnableSwagger2 注解、依赖是否完整、Controller 扫描路径是否正确
  • 问题2：项目启动报错依赖冲突
  • 解决方案：统一 Swagger 版本为 2.9.2，删除冗余重复依赖

七、总结

SpringBoot 整合 Swagger2 核心流程可总结为三步：引入核心依赖 → 编写Swagger配置类并开启功能 → 使用注解优化接口文档。

整合完成后，彻底解决了手动维护接口文档的痛点，实现了文档自动生成、实时更新、在线调试，大幅提升前后端协同开发效率，是 Java 后端项目开发的必备配置。


作 者：南烛
链 接：https://www.itnotes.top/archives/1427
来 源：IT笔记
文章版权归作者所有，转载请注明出处！


spring cloudSpring MVCspringbootswagger2性能优化接口文档教程整合解决方案
上一篇
下一篇