Swagger UI所有API端点示例值显示为null的排查求助

1. 聚焦RequestMappingInfoHandlerMapping的注入变更 #

• 你给该类Autowiring添加@Qualifier后，先确认注入的实例是否正确。如果注入了非默认的HandlerMapping，可能导致Swagger无法扫描到控制器方法的元数据（包括示例值相关注解）。
• 快速验证：临时移除@Qualifier，重启服务后看Swagger示例值是否恢复。如果恢复，说明当前注入的HandlerMapping未包含Swagger所需的请求映射信息，需要调整Qualifier指向的bean，或者确保该HandlerMapping能完整暴露控制器方法细节。

2. 确认Swagger依赖类型（排除SpringFox后锁定SpringDoc） #

• 代码里没SpringFox，大概率用的是SpringDoc OpenAPI（Spring官方推荐的Swagger替代方案）。SpringDoc依赖Spring MVC的HandlerMapping获取请求映射的方法信息，若替换默认HandlerMapping，可能导致它无法读取@Schema(example = "...")、@ExampleObject这类注解。
• 检查项目依赖是否包含springdoc-openapi-starter-webmvc-ui，再查看SpringDoc的配置类（如果存在），确认是否有针对HandlerMapping的扫描规则配置。

3. 验证控制器与实体类的示例注解 #

• 抽查几个之前有示例值的接口，确认方法参数、返回对象上的示例注解（比如@RequestParam(example = "xxx")、实体字段的@Schema(example = "...")）是否完好，有没有被误删或注释。

4. 检查OpenAPI元数据的生成情况 #

• 访问Swagger的原始API元数据接口（通常是/v3/api-docs），搜索目标字段，看JSON中是否包含example属性。如果JSON里没有，说明是后端生成阶段的问题；如果JSON里有但UI没显示，清空浏览器缓存或换浏览器排除前端缓存影响。

5. 排查Spring上下文的HandlerMapping注册 #

• 启动服务时查看日志里的HandlerMapping注册信息，确认你注入的RequestMappingInfoHandlerMapping是否包含所有控制器的请求映射。如果它只注册了部分映射，Swagger自然拿不到完整元数据。
• 若启用了Spring Boot Actuator，可通过/beans端点查看所有HandlerMapping类型的bean，对比添加@Qualifier前后的注册差异。

内容的提问来源于stack exchange，提问作者NDB