Spring Boot 2.6+ 必须使用 springfox-boot-starter 3.0.0+ 替代 springfox-swagger2，因老版本未适配 Spring 5.3 参数解析机制；@EnableSwagger2 已废弃，需改用 @EnableOpenApi，并确保包扫描、注解位置及泛型处理正确。
Spring Boot 2.6+ 用 springfox 会启动失败
直接加 springfox-swagger2 和 springfox-swagger-ui 依赖，项目大概率报错：启动时抛出 NoClassDefFoundError: springfox/documentation/schema/ModelRef 或卡在 DocumentationPluginsManager 初始化。这不是配置问题，是版本断层——Spring Boot 2.6 默认升级到 Spring 5.3，而老版 springfox（比如 2.9.2）压根没适配 Spring MVC 的新参数解析机制。
- Spring Boot 2.6.x / 2.7.x → 必须用
springfox-boot-starter3.0.0+（注意不是 swagger2，是官方重写的 starter） - 若坚持用 2.9.2，请降级 Spring Boot 到 2.5.15（不推荐，安全补丁滞后）
-
@EnableSwagger2在 3.0+ 已废弃，改用@EnableOpenApi
@Api 和 @ApiOperation 注解不生效
写了注解但 Swagger UI 里看不到接口或描述，常见原因是没让 Controller 类被 Docket 扫描到，或者注解用在了错误位置。
- 确保
Docketbean 的select().apis()包含你的 Controller 包路径，例如RequestHandlerSelectors.basePackage("com.example.api") -
@Api必须加在类上（不是方法），@ApiOperation加在方法上；如果用了 Spring WebFlux，这两个注解无效，得换@Operation（OpenAPI 3 标准） - 接口返回类型要是 Spring MVC 能处理的（如
ResponseEntity<user></user>可以，Mono<user></user>需额外配置springfox.documentation.schema.TypeNameExtractor）
接口参数显示为 ? extends Object 或无法解析泛型
比如 List<order></order> 在文档里变成 Array>，或自定义泛型响应体（如 Result<page>></page>）字段全空。这是 springfox 对 Java Type 泛型擦除后信息丢失的典型表现。
Java 接口排错助手
下载
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
- 避免在 DTO 中直接写嵌套泛型，改用具体类型别名：
public class UserPage extends Page<user> { }</user> - 对
Result<t></t>这类包装类，在Docket配置里加genericModelSubstitutes(Result.class) - 不要依赖
@ApiModel的subTypes自动推导，手动用@ApiModelProperty(dataType = "string")指定关键字段类型
YAML 格式文档生成失败或 404
想导出 OpenAPI 3 的 swagger.yaml 但访问 /v3/api-docs 返回 404，或下载按钮点不动。这通常是因为没启用 OpenAPI 3 端点，或路径被其他过滤器拦截。
立即学习“Java免费学习笔记（深入）”；
- 确认引入的是
springfox-boot-starter（3.x），不是旧的swagger2；后者只提供/v2/api-docs - 检查是否配置了
springfox.documentation.open-api.v3.enabled=true（Spring Boot 配置文件中） - 若用了 Spring Security，需放行
/v3/api-docs/**和/swagger-ui/**，否则登录拦截会导致 UI 白屏
