Swagger3与Spring Boot 2.6+集成需彻底清除springfox依赖，仅保留springdoc-openapi-ui；@Operation需配合@Parameter等注解显式声明参数；配置须通过application.yml统一管理，禁用UI需按profile控制并关闭api-docs。

Swagger3依赖冲突导致启动失败

Spring Boot 2.6+ 默认启用 SpringDoc，但老项目若残留 springfox-swagger2 或 springfox-swagger-ui，会因 RequestMappingHandlerMapping 冲突直接报错，典型错误是 Failed to start bean 'documentationPluginsBootstrapper'。

必须彻底清理旧 Swagger 依赖：

• 删掉所有含 io.springfox 的 dependency
• 确认 pom.xml 中只保留 org.springdoc:springdoc-openapi-ui（推荐 1.7.0+，适配 Spring Boot 2.7/3.x）
• 若用 Gradle，检查是否意外引入了 springfox 传递依赖，加 exclude group: 'io.springfox'

@Operation 和 @ApiResponse 注解不生效

OpenAPI 3 注解默认不扫描 Controller 方法参数，光写 @Operation 没用；必须配合 @Parameter 显式声明路径、查询、请求体参数，否则文档里看不到入参结构或示例。

常见遗漏点：

立即学习“Java免费学习笔记（深入）”；

• @RequestBody 参数需加 @io.swagger.v3.oas.annotations.media.Content + @Schema 才能生成模型定义
• @PathVariable 和 @RequestParam 必须用 @Parameter(description = "...") 包裹，不能只靠 Javadoc
• 返回值类型若为泛型（如 Result<User>），需在 @ApiResponse 中用 implementation = User.class 指定实际类型

示例：正确标注一个带分页查询的接口

Gradle 9.8.0

下载

@GetMapping("/users")
@Operation(summary = "获取用户列表")
public Result<Page<User>> list(
    @Parameter(description = "页码", required = true) @RequestParam Integer page,
    @Parameter(description = "每页数量", required = true) @RequestParam Integer size) {
    // ...
}

配置类中 enable 设置被忽略

springdoc.api-docs.enabled=false 或 @Bean 配置里调用 setUseDoubleSlash(true) 等方法无效，大概率是因为没禁用默认配置自动装配——SpringDoc 会跳过你的 @Configuration 类，直接走 starter 的 SpringDocConfiguration。

解决方式只有两个：

• 在 application.yml 里统一配，比如：
  

  springdoc:<br>  api-docs:<br>    enabled: true<br>  swagger-ui:<br>    path: /swagger-ui.html

• 如果非要 Java 配置，必须加 @Primary 并确保类名不是 SpringDocConfiguration（避免重名覆盖）
• 注意：Spring Boot 3.x 要求 springdoc.show-actuator=true 才能在 /actuator/openapi 吐出 JSON，否则 404

生产环境暴露 Swagger UI 的风险与开关逻辑

Swagger UI 默认在所有 profile 下都可用，但 /swagger-ui.html 页面一旦上线，等于把接口契约、参数规则甚至示例值全公开，容易被爬取或误用。

安全做法是按 profile 控制：

• 开发/测试环境用 spring.profiles.active=dev，并配 springdoc.swagger-ui.enabled=true
• 生产环境必须设 springdoc.swagger-ui.enabled=false，且建议在启动时加 JVM 参数 -Dspringdoc.swagger-ui.enabled=false 防覆盖
• 即使关闭 UI，/v3/api-docs JSON 仍存在，如需彻底隐藏，得同时设 springdoc.api-docs.enabled=false

别指望靠拦截器或 WebSecurity 忽略 swagger 路径来“伪装”关闭——JSON 接口本身没权限校验，只要路径可访问，文档就泄露。