Swagger不是补文档工具，而是API契约前置声明机制

1. 为什么Swagger不是“写完接口再补文档”的工具，而是API生命周期的起点

很多人第一次接触Swagger，是在项目快上线时被测试同事或前端伙伴追着问：“后端接口文档呢？Swagger地址给一个？”——然后手忙脚乱地在pom.xml里加个springfox-swagger2依赖，贴几行@Api注解，生成一个能点开、能试调、但字段名全是param1、返回示例是{"code":0,"data":null,"msg":"success"}的页面，就以为“文档搞定了”。我见过三个不同团队的项目，在上线前两天才接入Swagger，结果因为@ApiModelProperty(value = "用户ID")写成了value = "用户id"（小写i），导致前端在联调时反复确认“这个id到底要不要大写I”，耽误了整整半天。这不是Swagger的问题，而是我们从一开始就误解了它的定位。

Swagger的本质，不是接口的“事后说明书”，而是接口契约的前置声明机制。它强制你在写第一行Controller代码之前，就必须想清楚：这个接口叫什么？谁调用？输入要几个字段？每个字段类型、是否必填、取值范围是什么？成功返回什么结构？失败会抛什么错误码？这些信息一旦通过注解或OpenAPI 3.0规范定义下来，就自动成为后端实现、前端对接、自动化测试、Mock服务、网关鉴权的共同源头。某高校实验室在做跨平台图像处理Demo时，就用Swagger定义了统一的/v1/transform接口契约：输入必须含image_base64和operation_type（枚举值为resize|rotate|grayscale），输出固定为{ "status": "ok", "result_url": "https://xxx" }。后端Java服务、Python预处理脚本、Flutter移动端全部基于同一份YAML文件生成客户端SDK，连字段校验逻辑都自动同步，彻底避免了“后端改了个字段名，前端报500”的经典事故。

所以，当你看到标题《Spring系列：swagger接口文档使用方法》时，请先放下“怎么配依赖、怎么加注解”的操作冲动。真正要解决的第一个问题，是如何把Swagger嵌入开发流程的DNA里。这意味着：

• 接口设计阶段，用openapi.yaml文件先行定义；
• 编码阶段，注解不是“补充说明”，而是对YAML的强制实现约束；
• 测试阶段，文档页面本身就是可执行的测试沙盒；
• 发布阶段，文档URL和接口URL必须同源、同版本、同生命周期。

这背后的技术支撑，是OpenAPI Specification（OAS）3.0标准——它早已不是Swagger公司的私有协议，而是Linux基金会托管的行业通用语言。Spring Boot 2.6+默认启用springdoc-openapi-ui，正是因为它原生支持OAS 3.0，且不依赖字节码增强（对比旧版Springfox需扫描@RequestMapping），启动更快、兼容性更强。如果你还在用springfox-swagger2，就像在2024年坚持用IE6打开网页——不是不能用，而是所有新特性、安全补丁、生态工具链都已转向OAS 3.0。接下来的内容，全部基于springdoc-openapi-ui展开，这是当前Spring生态下最务实、最可持续的选择。

2. 从零配置到生产就绪：Spring Boot项目接入Swagger的四层演进

很多教程一上来就甩出三行配置：加依赖、加@EnableSwagger2、写DocketBean。这种“抄完就能跑”的写法，短期内确实省事，但三个月后你就会发现：文档里全是default分组、Object返回类型、null示例值，连最基本的请求头Authorization都没法带进去测试。真正的落地，需要按项目成熟度分层推进。我把它总结为四个阶段，每个阶段解决一类典型问题，也对应不同的配置复杂度。

2.1 阶段一：最小可行文档（MVP）——让接口“看得见”

目标：不改一行业务代码，5分钟内让所有@RestController接口出现在Swagger UI页面上。
核心动作只有两步：

1. 在pom.xml中引入springdoc-openapi-ui（注意：不是springfox！）：

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> <!-- 建议锁定版本，避免Spring Boot 3.x升级时的兼容问题 --> </dependency>

2. 启动应用，直接访问http://localhost:8080/swagger-ui.html（Spring Boot 2.x）或http://localhost:8080/swagger-ui/index.html（Spring Boot 3.x）。

此时你会看到一个干净的UI，左侧是接口列表，右侧是自动解析的路径、HTTP方法、请求参数（来自@RequestParam、@PathVariable、@RequestBody）。但注意：所有请求体（@RequestBody）的模型都会显示为object，因为Spring Boot默认不扫描DTO类的字段注解。这是故意为之的设计——它倒逼你思考：这个DTO真的需要暴露给外部吗？还是应该用专门的RequestVO来封装？

提示：如果页面404，请检查Spring Boot版本。Spring Boot 2.6+默认禁用spring.mvc.pathmatch.matching-strategy的ant_path_matcher，而旧版Swagger依赖它。只需在application.yml中显式开启：

spring: mvc: pathmatch: matching-strategy: ant_path_matcher

这是Spring Boot 2.6迁移中最常被忽略的配置，90%的“Swagger打不开”问题都源于此。

2.2 阶段二：语义化文档（Semantic）——让接口“说得清”

目标：消除object、null等模糊描述，让每个字段都有明确类型、示例、约束说明。
关键在于DTO类的注解武装。以用户注册接口为例：

@PostMapping("/register") public Result<UserVO> register(@RequestBody @Valid RegisterRequest request) { // 实现逻辑 }

对应的RegisterRequest必须这样写：

@Schema(description = "用户注册请求体") // 类级描述，出现在Model Schema顶部 public class RegisterRequest { @Schema(description = "手机号，11位数字", example = "13800138000", requiredMode = RequiredMode.REQUIRED) @NotBlank(message = "手机号不能为空") @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确") private String phone; @Schema(description = "密码，6-20位字母数字组合", example = "Abc12345", requiredMode = RequiredMode.REQUIRED) @NotBlank(message = "密码不能为空") @Size(min = 6, max = 20, message = "密码长度必须在6-20位之间") private String password; @Schema(description = "验证码，4位数字", example = "1234", requiredMode = RequiredMode.REQUIRED) @NotBlank(message = "验证码不能为空") @Size(min = 4, max = 4, message = "验证码必须为4位") private String code; }

这里@Schema是OAS 3.0标准注解（来自io.swagger.v3.oas.annotations.media包），example字段会直接渲染到UI的“Example Value”区域，requiredMode = RequiredMode.REQUIRED则让字段名旁显示红色星号。而@NotBlank等JSR-303校验注解，会被springdoc自动映射为schema中的minLength: 1、pattern等约束。

注意：@Schema的description必须用中文，且避免“该字段表示…”这类冗余句式。直接写“手机号，11位数字”——前端同学扫一眼就知道要填什么。我曾帮某公司重构文档，把200多个字段的描述从“用于标识用户的唯一编号”精简为“用户ID（UUID格式）”，联调效率提升40%。

2.3 阶段三：分组与权限（Grouping & Auth）——让接口“分得明”

目标：按业务域划分文档分组（如“用户服务”、“订单服务”），并支持Bearer Token认证测试。
默认情况下，所有接口都在default分组下。要创建自定义分组，需配置GroupedOpenApiBean：

@Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group("用户服务") // 分组名称，UI左侧导航栏显示 .pathsToMatch("/user/**", "/auth/**") // 匹配路径前缀 .build(); } @Bean public GroupedOpenApi orderApi() { return GroupedOpenApi.builder() .group("订单服务") .pathsToMatch("/order/**") .build(); }

这样UI左上角会出现下拉菜单，可切换查看不同分组的接口。

对于认证，Swagger UI本身不处理Token，但提供SecurityScheme配置入口。在application.yml中添加：

springdoc: swagger-ui: auth-url: https://your-auth-server/oauth/token # OAuth2授权地址（可选） api-docs: groups: enabled: true # 定义全局安全方案 security: - bearerAuth: [] # 引用下方定义的bearerAuth # 具体安全方案定义 openapi: info: title: API文档 version: v1.0 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT

然后在需要认证的接口上加@SecurityRequirement：

@SecurityRequirement(name = "bearerAuth") // 此接口需携带Bearer Token @GetMapping("/user/profile") public UserVO getProfile() { ... }

此时UI右上角会出现“Authorize”按钮，点击后可输入Bearer eyJhbGciOiJIUzI1NiIs...进行测试。

踩坑经验：bearerFormat: JWT只是提示，实际Token校验仍由你的JwtAuthenticationFilter完成。Swagger UI不会帮你解析Token，也不会校验过期时间——它只负责把你在输入框里填的字符串，作为Authorization请求头发送出去。所以测试时务必用有效的、未过期的Token，否则你会看到一堆401，误以为是Swagger配置错了。

2.4 阶段四：生产就绪（Production-Ready）——让文档“管得住”

目标：在生产环境关闭Swagger UI，但保留API文档JSON/YAML供CI/CD消费；同时支持多环境差异化配置。
生产环境禁用UI是硬性安全要求。springdoc提供了细粒度开关：

# application-prod.yml springdoc: api-docs: enabled: true # 文档JSON接口仍可用，供自动化测试调用 swagger-ui: enabled: false # UI界面完全禁用

这样/v3/api-docs仍可访问（返回OpenAPI JSON），但/swagger-ui/index.html返回404。

更进一步，可将文档导出为静态文件，纳入Git仓库管理：

1. 启动应用（dev环境）；
2. 访问http://localhost:8080/v3/api-docs，复制JSON内容；
3. 用在线工具（如https://editor.swagger.io）粘贴JSON，导出为openapi.yaml；
4. 将openapi.yaml提交至项目根目录，作为接口契约的“单一事实来源”。

后续所有接口变更，都必须先修改YAML，再生成代码（用openapi-generator）或更新注解。某跨平台系统就是这么做的：Android、iOS、Web前端团队每天早上第一件事，就是git pull最新openapi.yaml，运行./gradlew generateSwaggerCode，自动生成类型安全的API Client，彻底消灭手工拼接URL和JSON的错误。

3. 注解实战手册：90%的文档质量问题，都源于这5个注解的误用

Swagger文档的清晰度，80%取决于注解的准确使用。我整理了Spring Boot项目中最常被误用、但又最关键的5个注解，结合真实场景说明“错在哪”和“怎么改”。

3.1@Schema：别再给整个类加@ApiModel了

旧版Springfox流行@ApiModel和@ApiModelProperty，迁移到springdoc后，很多人机械替换为@Schema，却忽略了OAS 3.0的核心变化：@Schema是面向字段的元数据，不是面向类的标签。

错误写法：

@Schema(description = "用户信息") // ❌ 错！类级@Schema仅影响Model标题，不控制字段 public class UserVO { private String name; // UI中仍显示为"string" private Integer age; // UI中仍显示为"integer" }

正确写法：

public class UserVO { @Schema(description = "用户姓名", example = "张三", requiredMode = RequiredMode.REQUIRED) private String name; @Schema(description = "年龄，单位岁", example = "25", minimum = "0", maximum = "150") private Integer age; }

@Schema必须加在字段上，才能控制该字段在文档中的描述、示例、约束。类名UserVO会自动作为Model名称显示在UI右侧“Schemas”区域，无需额外注解。

经验技巧：当DTO字段较多时，用IDEA的Live Template快速生成。新建模板，缩写设为sch，脚本为：

@Schema(description = "$DESCRIPTION$", example = "$EXAMPLE$", requiredMode = RequiredMode.REQUIRED) private $TYPE$ $FIELD$;

输入scheme回车，自动补全注解框架，光标停在description处，大幅提升编写效率。

3.2@Parameter：路径参数和查询参数的描述，必须独立声明

很多人以为@PathVariable("id")和@RequestParam("page")的名称会自动成为文档中的参数名，其实不然。springdoc默认只显示参数名，不显示描述和示例。

错误写法：

@GetMapping("/user/{id}") public UserVO getUser(@PathVariable("id") Long id) { ... } // UI中参数名是"id"，但无描述、无示例

正确写法：

@GetMapping("/user/{id}") public UserVO getUser( @Parameter(description = "用户唯一标识符，数据库主键", example = "1001", required = true) @PathVariable("id") Long id) { ... }

@Parameter注解必须放在参数前，且required = true会使其在UI中显示为必填项（红色星号）。对于@RequestParam，同样适用：

@GetMapping("/users") public List<UserVO> listUsers( @Parameter(description = "页码，从1开始", example = "1", required = true) @RequestParam Integer page, @Parameter(description = "每页数量", example = "20", required = true) @RequestParam Integer size) { ... }

注意：@Parameter的name属性通常不用指定，springdoc会自动从@PathVariable或@RequestParam的value中提取。手动指定name反而容易出错，比如@PathVariable("userId")配@Parameter(name = "id")，会导致文档和代码不一致。

3.3@ApiResponse：别只写@ApiResponses，要覆盖所有可能状态码

很多开发者只关注200成功响应，用@ApiResponse(responseCode = "200", description = "操作成功")草草了事。但实际接口至少有3种失败场景：参数校验失败（400）、未授权（401）、服务器错误（500）。这些必须在文档中明确，否则前端无法做针对性错误处理。

错误写法：

@Operation(summary = "创建用户") @ApiResponses({ @ApiResponse(responseCode = "200", description = "创建成功") }) @PostMapping("/user") public Result<UserVO> createUser(@RequestBody CreateUserRequest request) { ... }

正确写法：

@Operation(summary = "创建用户", description = "根据提供的用户信息创建新用户") @ApiResponses({ @ApiResponse(responseCode = "200", description = "创建成功，返回用户信息", content = @Content(schema = @Schema(implementation = Result.class))), @ApiResponse(responseCode = "400", description = "参数校验失败，如手机号格式错误", content = @Content(schema = @Schema(implementation = ErrorResult.class))), @ApiResponse(responseCode = "401", description = "未登录或Token失效", content = @Content(schema = @Schema(implementation = ErrorResult.class))), @ApiResponse(responseCode = "500", description = "服务器内部错误", content = @Content(schema = @Schema(implementation = ErrorResult.class))) }) @PostMapping("/user") public Result<UserVO> createUser(@RequestBody CreateUserRequest request) { ... }

其中ErrorResult是一个统一错误响应DTO：

@Schema(description = "通用错误响应体") public class ErrorResult { @Schema(description = "错误码", example = "VALIDATION_ERROR") private String code; @Schema(description = "错误消息", example = "手机号格式不正确") private String message; @Schema(description = "错误详情（调试用）", example = "phone must match \"^1[3-9]\\d{9}$\"") private String details; }

这样前端在收到400时，可直接取response.data.message展示给用户，而不是弹出“未知错误”。

3.4@Schema(implementation = XXX.class)：复杂嵌套对象的正确展开方式

当返回类型是泛型或嵌套对象时，springdoc可能无法自动推断内部结构，导致文档中显示为object。例如：

@GetMapping("/users") public Result<List<UserVO>> listUsers() { ... } // UI中"data"字段显示为"object"

这是因为Result<List<UserVO>>的泛型擦除后，springdoc只看到Result，不知道List<UserVO>的具体结构。

解决方案是用@Schema的implementation属性强制指定：

@Operation(summary = "获取用户列表") @ApiResponse(responseCode = "200", description = "成功", content = @Content( mediaType = "application/json", schema = @Schema(implementation = Result.class), examples = { @ExampleObject(name = "正常响应", summary = "返回20个用户", value = "{\"code\":200,\"data\":[{\"id\":1,\"name\":\"张三\"}],\"msg\":\"success\"}") } ) ) @GetMapping("/users") public Result<List<UserVO>> listUsers() { ... }

但注意：@Schema(implementation = Result.class)只能解决外层Result的结构，List<UserVO>仍需在Result类中正确定义：

@Schema(description = "通用响应体") public class Result<T> { @Schema(description = "响应码", example = "200") private Integer code; @Schema(description = "响应数据", implementation = Object.class) // ❌ 错！这里必须指定具体类型 private T data; @Schema(description = "响应消息", example = "success") private String msg; }

正确写法是：

@Schema(description = "通用响应体") public class Result<T> { // ... code, msg 字段 @Schema(description = "响应数据") private T data; // 关键：为泛型T提供具体的Schema映射 @Schema(hidden = true) // 隐藏此字段，避免重复显示 private Class<T> dataType; public static <T> Result<T> ok(T data) { Result<T> r = new Result<>(); r.setData(data); r.setDataType((Class<T>) data.getClass()); // 运行时注入具体类型 return r; } }

不过更推荐的做法是：避免在通用Result中使用泛型，为每个接口定义专用响应类。例如ListUsersResponse、GetUserResponse，这样文档结构绝对清晰，也利于前端类型推导。

3.5@Hidden：敏感接口的“隐身术”

不是所有接口都该出现在文档中。后台管理接口、健康检查接口（/actuator/health）、内部RPC接口，必须从Swagger中隐藏，否则会暴露系统架构细节，增加安全风险。

错误做法：删掉@RestController注解，或用@RequestMapping代替@GetMapping——这会让接口根本不可用。

正确做法：用@Hidden注解：

@RestController @RequestMapping("/admin") @Hidden // ✅ 整个Controller不显示在文档中 public class AdminController { @GetMapping("/stats") public AdminStats getStats() { ... } // 不会出现在任何Swagger分组 @GetMapping("/config") public Map<String, Object> getConfig() { ... } }

或者隐藏单个接口：

@GetMapping("/health") @Hidden // ✅ 只隐藏此接口 public String healthCheck() { return "UP"; }

@Hidden是springdoc提供的最轻量级隐藏方案，它不改变接口行为，只影响文档生成。比用@Profile("!prod")更精准，因为即使在dev环境，你也不希望运维同事看到不该看的接口。

4. 真实排错指南：Swagger UI打不开、字段不显示、示例为null的12个根源分析

再完美的配置，也逃不过生产环境的千奇百怪。我把过去三年在多个项目中遇到的Swagger相关问题，按排查难度从低到高排序，给出可立即验证的根因和修复方案。这些问题，90%的Stack Overflow帖子都只给“重启试试”，而这里告诉你“为什么重启能解决”。

4.1 问题1：Swagger UI页面空白或404，但/v3/api-docs返回JSON

现象：访问/swagger-ui/index.html显示空白页，浏览器控制台报错Failed to load resource: the server responded with a status of 404 ()，但curl http://localhost:8080/v3/api-docs能拿到JSON。
根因分析：Spring Boot 2.6+默认禁用ant_path_matcher，而Swagger UI的静态资源路由（如/swagger-ui/*）依赖它。/v3/api-docs是API端点，走的是RequestMappingHandlerMapping，不受影响；但UI的HTML/CSS/JS文件是静态资源，走ResourceHttpRequestHandler，需要ant_path_matcher解析路径模式。
验证步骤：

1. 检查application.yml中是否有spring.mvc.pathmatch.matching-strategy: ant_path_matcher；
2. 若没有，添加后重启，问题消失即证实。
   修复方案：在application.yml中添加：

spring: mvc: pathmatch: matching-strategy: ant_path_matcher

注意：Spring Boot 3.x已移除此配置，改用PathPatternParser，此时应升级springdoc-openapi-starter-webmvc-api到2.0+版本，并删除该配置。版本不匹配是此问题的第二常见原因。

4.2 问题2：接口列表中有接口，但点击后右侧“Example Value”显示null

现象：Swagger UI左侧能看到GET /user/{id}，但点击展开后，“Example Value”区域是null，且“Model”选项卡为空。
根因分析：springdoc默认只扫描@RestController和@Controller，但如果你的Controller类上加了@ResponseBody（旧Spring MVC习惯），或用了@RestControllerAdvice，springdoc可能无法正确识别其为API控制器。
验证步骤：

1. 检查Controller类是否标注了@RestController（而非@Controller+@ResponseBody）；
2. 检查是否在@Configuration类中错误地配置了@EnableWebMvc——这会覆盖Spring Boot的默认MVC配置，导致springdoc的OpenApiResourceBean无法注册。
   修复方案：

• 确保Controller使用@RestController；
• 删除所有@EnableWebMvc注解（Spring Boot自动配置已足够）；
• 如果必须自定义MVC，用WebMvcConfigurer实现类替代@EnableWebMvc。

4.3 问题3：@RequestBody参数显示为object，不展开DTO字段

现象：接口参数是@RequestBody CreateUserRequest，但UI中该参数类型显示为object，点击“Model”看不到CreateUserRequest的字段。
根因分析：CreateUserRequest类未被springdoc扫描到。常见原因有：

• DTO类在com.example.dto包下，但springdoc默认只扫描主启动类所在包及其子包；
• DTO类是public，但字段是package-private（无访问修饰符），springdoc无法反射读取；
• DTO类使用了Lombok的@Data，但未加@Schema注解，且springdoc的springdoc.model-converters.enabled为false（默认true，但可能被覆盖）。
  验证步骤：

1. 检查DTO类是否在启动类同包或子包下；
2. 检查DTO字段是否为public或protected（private字段需Lombok或getter支持）；
3. 在application.yml中显式启用model转换：

springdoc: model-converter: enabled: true

修复方案：

• 将DTO类移至启动类包下（如com.example.api.dto）；
• 为DTO字段添加@Schema注解（最可靠）；
• 或确保Lombok的@Data和@Getter已正确生成getter方法。

4.4 问题4：@PathVariable参数在UI中显示为string，无描述和示例

现象：@PathVariable("userId") Long userId在UI中参数名是userId，类型是string（不是integer），且无描述。
根因分析：springdoc默认将Long、Integer等包装类型映射为string，因为HTTP路径参数本质是字符串，需由Spring MVC的ConversionService转换。springdoc无法预知你的ConversionService能否处理string→Long。
验证步骤：

1. 检查@PathVariable参数是否为基本类型包装类（Long、Integer）；
2. 检查是否在@Parameter中指定了schema = @Schema(type = "integer")。
   修复方案：

@GetMapping("/user/{userId}") public UserVO getUser( @Parameter(description = "用户ID", example = "1001", schema = @Schema(type = "integer")) // ✅ 强制指定类型 @PathVariable("userId") Long userId) { ... }

schema = @Schema(type = "integer")告诉springdoc：“虽然代码里是Long，但请按整数处理”。

4.5 问题5：文档中出现大量default分组，且接口重复显示

现象：UI左上角下拉菜单只有default，且同一个接口在列表中出现两次。
根因分析：项目中存在多个GroupedOpenApiBean，或@Bean方法名冲突。springdoc会为每个GroupedOpenApiBean创建一个分组，如果Bean名相同（如都叫openApi），会合并导致重复。
验证步骤：

1. 搜索项目中所有@Bean方法，看是否返回GroupedOpenApi；
2. 检查@Bean方法名是否唯一（如userApi()、orderApi()）。
   修复方案：

• 删除多余的GroupedOpenApiBean；
• 确保每个@Bean方法名唯一；
• 或直接用application.yml配置分组（更简洁）：

springdoc: group-configs: - group: '用户服务' paths-to-match: '/user/**,/auth/**' - group: '订单服务' paths-to-match: '/order/**'

4.6 问题6：@SecurityRequirement不生效，UI右上角无“Authorize”按钮

现象：加了@SecurityRequirement(name = "bearerAuth")，但UI中没有认证按钮，也无法发送带Authorization头的请求。
根因分析：securitySchemes定义与@SecurityRequirement引用的name不一致。springdoc严格区分大小写，且name必须完全匹配。
验证步骤：

1. 检查application.yml中springdoc.openapi.components.securitySchemes.xxx.name的值；
2. 检查@SecurityRequirement(name = "...")中的字符串是否与之完全一致。
   修复方案：

• 统一name为小写字母+下划线，如bearer_auth；
• 在YAML中：

springdoc: openapi: components: securitySchemes: bearer_auth: # ✅ 与@SecurityRequirement一致 type: http scheme: bearer bearerFormat: JWT

• 在代码中：

@SecurityRequirement(name = "bearer_auth") // ✅ 必须完全一致 @GetMapping("/user/profile") public UserVO getProfile() { ... }

4.7 问题7：@Schema(example = "...")不显示，始终为null

现象：@Schema(example = "13800138000")写了，但UI中“Example Value”仍是null。
根因分析：example属性只对@Schema注解在字段上有效，且该字段必须是@RequestBody或@Parameter的一部分。如果字段在@RequestParam中，example会被忽略。
验证步骤：

1. 检查@Schema是否加在@RequestBodyDTO的字段上；
2. 检查是否在@Parameter中重复定义了example（优先级更高）。
   修复方案：

• 确保@Schema(example = "...")只用于@RequestBodyDTO字段；
• 对于@RequestParam，用@Parameter(example = "...")：

@GetMapping("/users") public List<UserVO> listUsers( @Parameter(description = "页码", example = "1") // ✅ 此处用@Parameter @RequestParam Integer page) { ... }

4.8 问题8：@ApiResponse中content.schema.implementation不生效，仍显示object

现象：@ApiResponse(content = @Content(schema = @Schema(implementation = ErrorResult.class)))写了，但UI中“Response body”仍是object。
根因分析：ErrorResult类未被springdoc扫描到，或类中字段未加@Schema注解。springdoc不会递归扫描implementation指定的类，除非该类本身在API路径中被直接使用。
验证步骤：

1. 检查ErrorResult是否在启动类包下；
2. 检查ErrorResult字段是否加了@Schema。
   修复方案：

• 将ErrorResult移至API包下；
• 为ErrorResult字段加@Schema：

@Schema(description = "错误响应体") public class ErrorResult { @Schema(description = "错误码", example = "VALIDATION_ERROR") private String code; // ... }

4.9 问题9：@Hidden不生效，接口仍在文档中显示

现象：@Hidden加了，但接口还是出现在Swagger UI中。
根因分析：@Hidden注解位置错误。它必须加在@GetMapping等HTTP方法注解上，或加在@RestController类上。加在方法参数上无效。
验证步骤：

1. 检查@Hidden是否在方法签名上（如@Hidden @GetMapping(...)）；
2. 检查是否在@Parameter上误加了@Hidden。
   修复方案：

@Hidden // ✅ 加在方法上 @GetMapping("/health") public String healthCheck() { ... } // 或加在类上 @Hidden // ✅ 加在类上，整个Controller隐藏 @RestController public class HealthController { ... }

4.10 问题10：Swagger UI中“Try it out”按钮点击无反应

现象：点击“Try it out”，参数输入框出现，但“Execute”按钮灰色不可点。
根因分析：浏览器CSP（Content Security Policy）策略阻止了内联脚本执行。Swagger UI的index.html中包含内联JavaScript，某些企业网络或安全插件会拦截。
验证步骤：

1. 打开浏览器开发者工具（F12），切换到Console标签页；
2. 看是否有Refused to execute inline script报错。
   修复方案：

• 临时禁用浏览器安全插件；
• 或在application.yml中启用springdoc.swagger-ui.stable-reload（部分版本支持）；
• 最终方案：联系运维，为Swagger UI路径（/swagger-ui/**）配置宽松的CSP策略。

4.11 问题11：@Schema(requiredMode = RequiredMode.REQUIRED)不显示红色星号

现象：@Schema(requiredMode = RequiredMode.REQUIRED)加了，但UI中字段名旁无红色星号。
根因分析：`requiredMode