springdoc-openapi 是当前唯一靠谱选择，因旧版已停更且与 Spring Boot 2.6+ 冲突，而它基于 OpenAPI 3、无需 WebMvcConfigurer、天然兼容新版本。
Swagger 在 Java 项目里不是“配好就能用”，而是“不踩坑才真能用”——Spring Boot 2.6+ 默认禁用 WebMvcConfigurer 的自动配置，Swagger2 直接失效；springdoc-openapi 成为事实标准，但版本选错或路径冲突照样 404。
为什么 springdoc-openapi 是当前唯一靠谱选择
旧版 swagger-springmvc 和 springfox-swagger2 已停止维护，且与 Spring Boot 2.6+ 的 spring.mvc.pathmatch.matching-strategy=ant_path_matcher 冲突，启动报 NoHandlerFoundException。Spring 官方推荐的 springdoc-openapi 基于 OpenAPI 3，无需额外配置 WebMvcConfigurer，天然兼容新版本。
- 必须用
springdoc-openapi-ui（非springdoc-openapi-webmvc-core单独引入），否则 UI 页面 404 - Maven 依赖要和 Spring Boot 版本对齐：
spring-boot-starter-parent 2.7.x对应springdoc-openapi-ui 1.6.x；3.0.x对应2.0.x - 默认文档地址是
/v3/api-docs（不是/v2/api-docs），UI 入口是/swagger-ui.html（注意后缀是 .html，不是 /swagger-ui/）
配置类写法：别碰 @EnableSwagger2，也别手动注册 Docket
@EnableSwagger2 和 Docket 属于已淘汰的 springfox 体系，混用会导致 Bean 冲突、Swagger UI 加载空白。新版全部靠配置项驱动，零 Java 配置也能跑起来。
- 最简启动：只加依赖，不写任何配置类，访问
/swagger-ui.html就能看到基础文档 - 如需自定义标题、描述、版本，用
application.yml：
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
doc-expansion: none
tags-sorter: alpha
info:
title: 订单服务 API
version: 1.0.0
description: 支付与履约相关接口
- 切勿在配置类里 return new Docket(...) 或 @Bean Docket —— 这是过期范式，会覆盖 springdoc 自动装配
接口注解怎么写才生效：重点不是 @Api，而是 @Operation 和 @Parameter
旧注解 @Api、@ApiOperation 来自 swagger-annotations，虽仍可用，但推荐统一用 io.swagger.v3.oas.annotations 下的新注解，语义更清晰、支持 OpenAPI 3 标准字段。
立即学习“Java免费学习笔记（深入）”；
- 类级说明用
@Tag(name = "OrderController", description = "订单操作") - 方法级必须加
@Operation(summary = "创建订单", description = "返回订单 ID 和支付链接") - 路径参数用
@Parameter(description = "订单 ID", required = true)注在@PathVariable参数上 - 请求体对象不用额外注解，只要字段有
@Schema(description = "用户手机号")就能透出到文档 - 忽略某个接口？加
@Hidden，比@ApiIgnore更可靠
生产环境关闭 Swagger：别只删依赖，得关掉资源加载
仅在 application-prod.yml 里删掉 springdoc 配置项不够——静态资源（/swagger-ui.html、/webjars/）仍可被直接访问，存在信息泄露风险。
- 必须加配置彻底禁用：
springdoc:
api-docs:
enabled: false
swagger-ui:
enabled: false
- 更稳妥做法：用 profile 控制依赖，Maven 中将
springdoc-openapi-uiscope 设为runtime，并在 prod profile 中 exclude 它 - 注意：Spring Security 若未放行
/v3/api-docs/**和/swagger-ui.html，开发环境也会 403 —— 不是 Swagger 挂了，是权限拦住了
真正麻烦的从来不是加几行配置，而是旧项目里残留的 springfox 依赖、混用的注解包、以及没意识到 /v3/api-docs 和 /v2/api-docs 是两个世界。
