Spring Boot 集成 Swagger3 应使用 SpringDoc OpenAPI（非已停更的 Springfox），根据版本选择对应依赖：2.6~3.1用springdoc-openapi-ui，3.2+用springdoc-openapi-starter-webmvc-ui；启动后访问/swagger-ui/index.html即可查看自动生成功能文档，并支持通过@Tag、@Operation等注解增强描述。
Spring Boot 集成 Swagger3，本质是接入基于 OpenAPI 3.0 规范的文档生成方案，当前主流且官方推荐的方式是使用 SpringDoc OpenAPI，而非已停更的 Springfox（Swagger2）。它开箱即用、适配 Spring Boot 2.6+ 和 3.x，自动扫描接口、生成 JSON/YAML 描述，并内置 Swagger UI 页面。
引入正确的依赖
Spring Boot 2.6 及以后版本默认移除了对 Springfox 的兼容支持，必须使用 SpringDoc。根据你的 Spring Boot 版本选择对应依赖：
- Spring Boot 2.6 ~ 3.1：用
springdoc-openapi-ui（如 1.7.0） - Spring Boot 3.2+（Jakarta EE 9+）：用
springdoc-openapi-starter-webmvc-ui（如 2.3.0）
示例（Maven）：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.3.0</version> </dependency>
添加后无需额外启动配置，应用启动即生效。
访问默认 UI 页面
依赖生效后，Swagger UI 自动部署在以下路径（具体取决于 SpringDoc 版本）：
- v1.x：访问
http://localhost:8080/swagger-ui.html - v2.x（Spring Boot 3）：访问
http://localhost:8080/swagger-ui/index.html
页面会自动加载当前项目所有 @RestController 接口，展示路径、方法、参数、响应结构等，支持在线调试。
自定义文档元信息
通过 Java Config 注册 OpenAPI Bean，设置标题、版本、联系人等全局信息：
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("订单服务 API")
.version("v1.2.0")
.description("提供订单创建、查询与状态更新功能")
.contact(new Contact().name("API 支持组").email("api@company.com")));
}
}
这些信息会显示在 UI 页眉，并写入 OpenAPI JSON/YAML 文档根节点的 info 字段。
控制扫描范围与增强可读性
默认扫描全部 @RestController，可通过配置缩小范围或补充说明：
- 在
application.yml中指定包路径：springdoc.packages-to-scan: com.example.api - 为接口类加
@Tag(name = "用户管理", description = "用户注册、登录相关接口")分组归类 - 为方法加
@Operation(summary = "根据ID查询用户", description = "返回完整用户信息")补充语义 - 为参数加
@Parameter(description = "用户唯一标识")或直接用@Schema描述 DTO 字段
这些注解不改变逻辑，仅增强文档表达力，且完全基于 OpenAPI 3.0 原生规范，无 vendor lock-in。
