Spring Boot 3.x 4.x 项目中集成 Swagger（OpenAPI）

你想要在 Spring Boot 3 项目中集成 Swagger（OpenAPI）来自动生成和管理 API 文档，这是后端开发中非常常见的需求。

一、核心说明

Spring Boot 3 基于 Jakarta EE，不再兼容传统的 springfox-swagger（适配 Java EE），因此需要使用 SpringDoc OpenAPI（适配 Jakarta EE）来实现 Swagger 功能，它是目前官方推荐的方案。

二、集成步骤（完整可运行）

1. 添加依赖（Maven/Gradle）

Maven（pom.xml）：

<!-- SpringDoc OpenAPI 核心依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- 推荐使用最新稳定版 -->
</dependency>

Gradle（build.gradle）：

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

2. 基础配置（可选，推荐）

在 application.yml 或 application.properties 中添加自定义配置，简化访问和基础信息：

springdoc:
  # Swagger UI 访问路径（默认 /swagger-ui.html）
  swagger-ui:
    path: /swagger-ui.html
    # 展开所有接口分组
    operationsSorter: method
    tagsSorter: alpha
  # API 文档基础信息
  api-docs:
    path: /v3/api-docs
  # 扫描的接口包（按需配置，不配置则扫描全部）
  packages-to-scan: com.example.demo.controller
  # 全局接口前缀（如有）
  paths-to-match: /api/**

# 自定义 API 文档信息（可通过配置类覆盖）
openapi:
  info:
    title: 示例项目 API 文档
    version: 1.0.0
    description: Spring Boot 3 集成 SpringDoc OpenAPI 示例
    contact:
      name: 开发者
      email: dev@example.com

3. 配置类（可选，增强自定义）

创建配置类自定义 Swagger 文档的详细信息（如分组、安全认证等）：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    /**
     * 自定义 OpenAPI 文档信息
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // API 基础信息
                .info(new Info()
                        .title("Spring Boot 3 + SpringDoc API 文档")
                        .version("1.0.0")
                        .description("这是基于 SpringDoc 实现的 Swagger 文档示例")
                        .contact(new Contact()  // 联系人信息
                                .name("开发者")
                                .email("dev@example.com")));
    }
}

4. 编写测试接口

创建一个示例 Controller，验证 Swagger 文档生成：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试接口，使用 Swagger 注解增强文档
 */
@RestController
@RequestMapping("/api/test")
// 接口分组标签
@Tag(name = "测试接口", description = "用于验证 Swagger 集成的测试接口")
public class TestController {

    /**
     * 示例接口：根据 ID 查询信息
     */
    @GetMapping("/{id}")
    // 接口描述
    @Operation(summary = "根据ID查询信息", description = "传入用户ID，返回对应的测试信息")
    public String getInfo(
            // 参数描述
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id) {
        return "测试信息：ID = " + id;
    }

    /**
     * 示例接口：获取欢迎信息
     */
    @GetMapping("/welcome")
    @Operation(summary = "获取欢迎信息", description = "无参数，返回固定欢迎语")
    public String welcome() {
        return "欢迎使用 Spring Boot 3 + Swagger！";
    }
}

5. 启动项目并访问

1. 启动 Spring Boot 项目（确保端口未被占用，默认 8080）；
2. 访问 Swagger UI 页面：http://localhost:8080/swagger-ui.html；
3. 页面中会显示你编写的接口，可直接在线测试接口调用。

三、关键注解说明（新手必看）

四、生产环境禁用 Swagger（重要）

为了安全，生产环境需关闭 Swagger 文档，可通过配置实现：

# application-prod.yml（生产环境配置）
springdoc:
  api-docs:
    enabled: false  # 关闭 API 文档生成
  swagger-ui:
    enabled: false  # 关闭 Swagger UI 页面

总结

1. 核心依赖：Spring Boot 3 需使用 springdoc-openapi-starter-webmvc-ui，而非传统的 springfox-swagger；
2. 访问路径：默认 Swagger UI 地址为 http://localhost:8080/swagger-ui.html，可通过配置自定义；
3. 核心要点：生产环境必须禁用 Swagger，避免接口信息泄露；通过 @Tag、@Operation 等注解可增强 API 文档的可读性。