不能共存，因Swagger 2与Springdoc均注册同名bean，导致BeanDefinitionOverrideException；Spring Boot 2.6+默认禁用bean覆盖，官方仅推荐Springdoc方案。
Swagger 3（Springdoc）和旧版 Swagger 2 能不能共存？
不能，强行共存会导致 BeanDefinitionOverrideException 或接口无法注册。Spring Boot 2.6+ 默认禁用 bean 覆盖，而 Swagger 2（springfox-swagger2）和 Springdoc（springdoc-openapi-ui）都尝试注册同名的 OpenAPI、GroupedOpenApi 等 bean。
- 旧项目还在用 Swagger 2？立刻停用
springfox-swagger2和springfox-swagger-ui，删掉所有@EnableSwagger2 - Spring Boot 2.6+ 必须加配置
spring.main.allow-bean-definition-overriding=true才能跑通 Swagger 2——但这只是掩耳盗铃，不解决根本冲突 - Springdoc 是当前唯一被 Spring Boot 官方推荐的方案，路径默认为
/swagger-ui.html（重定向到/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config）
Springdoc 的 springdoc.swagger-ui.path 不生效？
因为这个配置只控制 UI 页面的访问路径前缀（比如设成 /api-docs，那 UI 就在 /api-docs），但它不改变后端 OpenAPI spec 的实际暴露地址——那个由 springdoc.api-docs.path 控制，默认是 /v3/api-docs。
- 想把文档页面挪到
/docs？配springdoc.swagger-ui.path=/docs - 但浏览器打开
/docs后，前端仍会请求/v3/api-docs；如果这个路径被防火墙拦截或反向代理没透传，UI 就白屏 - 反向代理（如 Nginx）必须透传
/v3/api-docs和/swagger-ui/下的静态资源，否则出现Failed to load API definition - 检查是否误把
springdoc.api-docs.path改成了根路径（如/），这会导致 Spring MVC 路由冲突，整个应用启动失败
Controller 接口没出现在 Swagger UI 里？几个关键检查点
不是加了 @RestController 就自动进文档——Springdoc 默认只扫描带 @RestController 或 @RequestMapping 的类，且要求方法有明确的 HTTP method 注解（@GetMapping 等），不含 @RequestBody 或 @ResponseBody 的普通 @Controller 类会被跳过。
- 确认类上有
@Tag(name = "xxx")或至少一个@Operation(summary = "...")——没有注解的接口可能被过滤（尤其开启springdoc.show-actuator为 false 时） - DTO 字段用了 Lombok 的
@Data却没加@Schema？默认不会生成字段说明；加@Schema(description = "...")到字段或 getter 上才生效 - 泛型返回类型如
ResponseEntity<result>></result>，Springdoc 可能只解析到ResponseEntity，需用@ApiResponse显式声明implementation = User.class - 自定义参数解析器（如
@CurrentUserId这类注解）没配@Parameter(hidden = true)，会导致参数重复或类型识别失败
生产环境要不要关掉 Swagger UI？
要，但别只靠配置项。仅设 springdoc.api-docs.enabled=false 或 springdoc.swagger-ui.enabled=false 不够安全——这些只是禁用自动配置，如果 Controller 层用了 @Operation 等注解，OpenAPI spec 仍可能通过其他方式暴露（比如手动暴露 /v3/api-docs 端点）。
立即学习“Java免费学习笔记（深入）”；
- 最稳妥做法：用 Maven profile 区分环境，在
prodprofile 中完全排除依赖：springdoc-openapi-ui只在dev和test中scope=compile - 若必须保留依赖（如内部灰度环境需要），加 Spring Security 规则：拦截
/swagger-ui/**和/v3/api-docs/**，只放行内网 IP 或特定角色 - 注意
/actuator/openapi这类 Actuator 端点也可能输出 OpenAPI 内容，需一并关闭或保护
文档自动生成省事，但每个注解、每条配置背后都有明确的扫描逻辑和注入时机。漏掉一个 @Tag，少配一个 springdoc.packages-to-scan，或者代理层没透传 Accept: application/json 头，都可能导致 UI 空白或数据错乱——这些细节比“怎么装”重要得多。
