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>可以，Mono<User>需额外配置springfox.documentation.schema.TypeNameExtractor）
接口参数显示为 ? extends Object 或无法解析泛型
比如 List<Order> 在文档里变成 Array<?>，或自定义泛型响应体（如 Result<Page<User>>）字段全空。这是 springfox 对 Java Type 泛型擦除后信息丢失的典型表现。
- 避免在 DTO 中直接写嵌套泛型，改用具体类型别名：
public class UserPage extends Page<User> { } - 对
Result<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 白屏
