Spring Boot 3 整合 Swagger：打造现代化 API 文档系统（附完整代码 + 高级配置 + 最佳实践）

💡 前言

在前后端分离开发日益普及的今天，API 接口文档的管理与维护已经成为软件工程中不可或缺的一环。传统的接口文档往往存在更新滞后、格式混乱、协作困难等问题，严重影响开发效率和产品质量。

为了解决这一痛点，Swagger 应运而生。它是一个用于生成、描述和调用 RESTful 接口的强大工具集，能够帮助我们自动生成结构清晰、可交互的 API 文档，并支持在线调试功能。

随着 Spring Boot 进入 3.x 版本时代，官方推荐使用 SpringDoc OpenAPI 替代已停止维护的 springfox-swagger2。这是因为 SpringFox 不再兼容 Spring Boot 3 的 Jakarta EE 9+ 模块化命名空间。

本文将手把手带你完成：

✅ Spring Boot 3 中整合 Swagger 的最佳实践
✅ 使用 SpringDoc OpenAPI 实现接口文档自动生成
✅ 自定义文档标题、版本、联系人等信息
✅ 集成 Swagger UI 在线调试界面
✅ 多环境配置（开发/生产）
✅ 注解详解与实战示例
✅ 自定义分组、安全认证、跨域配置
✅ 性能优化建议与常见问题排查

无论你是初学者还是有一定经验的开发者，这篇文章都能让你快速上手 Spring Boot 3 的 Swagger 整合，并写出规范、高效、易维护的 API 文档！

📦 一、什么是 SpringDoc？为何选择它？

✅ SpringDoc 简介

SpringDoc 是一个开源项目，旨在为 Spring Boot 提供 OpenAPI 3.0 支持。OpenAPI 是 Swagger 的升级规范，提供了更强大、标准化的接口文档能力。

✅ SpringDoc 的核心模块：

模块	功能
springdoc-openapi-ui	提供 Swagger UI 界面
springdoc-openapi-webmvc-ui	支持 Spring Web MVC
springdoc-openapi-starter-webmvc-ui	快速集成 OpenAPI 的 starter
springdoc-openapi-security	支持安全认证（如 OAuth2）

✅ SpringDoc 相比 SpringFox 的优势

功能	SpringFox（旧）	SpringDoc（新）
是否支持 Spring Boot 3	❌ 否	✅ 是
使用包名	javax.*	jakarta.*
支持 OpenAPI 3.0	❌ 否	✅ 是
维护状态	已停止维护	活跃更新
社区活跃度	低	高
集成复杂度	高	简单

🔧 二、Spring Boot 3 整合 Swagger 步骤详解

Step 1：添加依赖（以 Maven 为例）

xml 复制代码

<!-- Spring Boot 3 + SpringDoc OpenAPI -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

📌 注意：

Spring Boot 3 使用的是 Jakarta EE 9+ 包名（即 jakarta.*），确保你使用的是 SpringDoc v2.x 及以上版本；
如果你使用 Spring Security，还需要额外添加权限配置。

Step 2：配置基础信息（application.yml）

yaml 复制代码

springdoc:
  api-docs:
    enabled: true                  # 启用/禁用API文档的访问
    path: /v3/api-docs            # 设置API文档的访问路径
  swagger-ui:
    path: /swagger-ui.html        # 设置Swagger UI的访问路径
    disable-swagger-default-url: true
    display-request-duration: true # 显示请求持续时间
  packages-to-scan: com.example.swaggerDemo.controller # 指定要扫描的包

Step 3：配置OpenAPI信息（SpringDocConfig）

java 复制代码

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI selfOpenAPI(){
        return new OpenAPI().info(new Info()
                        .title("我的API文档")
                        .description("Spring Boot 3 应用接口文档")
                        .version("v1.0.0"))
                .externalDocs(new ExternalDocumentation()
                        .description("更多文档")
                        .url("https://springdoc.org"));
    }

}

Step 4：创建测试 Controller 示例

java 复制代码

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "提供用户的增删改查操作")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户", description = "返回单个用户对象")
    public String getUserById(@PathVariable Long id) {
        return "用户ID：" + id;
    }

    @PostMapping
    @Operation(summary = "新增用户", description = "创建一个新的用户")
    public String createUser() {
        return "用户创建成功";
    }
}

Step 5：访问 Swagger UI 页面

启动项目后，访问以下地址即可打开 Swagger UI：

url 复制代码

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

你也可以访问 JSON 格式的 OpenAPI 文档：

url 复制代码

http://localhost:8080/v3/api-docs

🎯 三、常用注解详解（Swagger 3.0）

注解	描述
`@Tag`	用于类级别，描述控制器的作用
`@Operation`	用于方法级别，描述接口的功能
`@Parameter`	描述接口参数
`@Parameters`	描述多个参数
`@ApiResponse`	描述响应状态码及说明
`@ApiResponses`	描述多个响应
`@Schema`	替代旧版的 `@ApiModelProperty`，用于字段注释

示例：

java 复制代码

@GetMapping("/{id}")
@Operation(summary = "根据ID查询用户", description = "返回单个用户对象")
public ResponseEntity<User> getUserById(
        @Parameter(description = "用户唯一标识", required = true)
        @PathVariable("id") Long id) {
    // ...
}

🧪 四、高级配置：自定义分组 & 安全 & 跨域

✅ 1. 自定义接口分组

你可以通过配置文件或编程方式实现多组接口文档展示。

application.yml 配置：

yaml 复制代码

springdoc:
  group-configs:
    - group: "用户服务"
      paths-to-match: "/users/**"
    - group: "订单服务"
      paths-to-match: "/orders/**"

SpringDocConfig配置：

java 复制代码

@Bean
public GroupedOpenApi usersOpenApi(){
    return GroupedOpenApi.builder()
            .group("用户服务")
            .pathsToMatch("/users/**")
            .build();
}
    
@Bean
public GroupedOpenApi ordersOpenApi(){
    return GroupedOpenApi.builder()
            .group("订单服务")
            .pathsToMatch("/orders/**")
            .build();
}

✅ 2. 跨域配置（CORS）

如果你的前端应用部署在不同域名下，需开启 CORS 支持：

java 复制代码

@Configuration
@EnableWebMvc
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/v3/api-docs/**")
                .allowedOrigins("http://your-frontend-domain.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE");
    }
}

🧩 五、多环境配置（开发/生产）

你可以通过 application-{profile}.yml 文件来控制是否启用 Swagger。

application-dev.yml（开发环境启用）

yaml 复制代码

springdoc:
  swagger-ui:
    enabled: true
  api-docs:
    enabled: true

application-prod.yml（生产环境关闭）

yaml 复制代码

springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

🧱 六、性能优化建议

优化项	建议
减少扫描路径	使用 `springdoc.packages-to-scan` 指定扫描范围
关闭不必要的文档	生产环境禁用 Swagger UI 和 API Docs
使用缓存机制	对频繁访问的文档接口进行缓存处理
压缩输出内容	启用 GZIP 压缩减少网络传输量
异步加载文档	使用懒加载策略提升首屏加载速度

🧩 七、常见问题与解决方案

问题	解决方案
Swagger 页面打不开	检查路径是否正确（默认 `/swagger-ui.html`）
接口未显示	确保 Controller 方法有 `@RestController` 和注解描述
生产环境暴露文档	使用 profile 控制开关
跨域问题	添加 Spring Security 白名单或 CORS 配置
Spring Security 认证拦截	配置免登录访问 `/v3/` 和 `/swagger-ui/`

📘 八、总结对比表

功能	SpringFox（旧）	SpringDoc（新）
是否支持 Spring Boot 3	❌ 否	✅ 是
使用包名	javax.*	jakarta.*
支持 OpenAPI 3.0	❌ 否	✅ 是
维护状态	已停止维护	活跃更新
社区活跃度	低	高
集成复杂度	高	简单

🎁 九、结语

随着 Spring Boot 3 的发布，SpringDoc 成为了新一代 API 文档生成的标准工具。相比之前的 SpringFox，它不仅功能更加强大，而且兼容性更好、社区活跃度更高。

通过本文的学习，你应该已经掌握了如何在 Spring Boot 3 项目中整合 Swagger，包括：

✅ 快速搭建 OpenAPI 文档环境
✅ 使用 Swagger UI 查看和调试接口
✅ 使用注解丰富接口文档内容
✅ 多环境配置，保护生产文档
✅ 安全策略配置建议
✅ 分组管理、跨域支持、性能优化技巧

无论是企业级后台系统、电商平台，还是微服务架构，都应该合理使用 Swagger 来提升团队协作效率和接口质量。

🎯 点赞、收藏、转发本文，让更多开发者受益！