Spring集成Swagger时@ApiParam注解导致接口方法在swagger-ui不显示问题

问题原因及对应解决方案 #

1. 注解导入不匹配

这是最常见的诱因：如果项目依赖的Swagger规范版本和你导入的@ApiParam注解包路径不一致，会导致Swagger扫描接口时抛出解析异常，直接跳过该方法的加载：

• 若你使用的是Springfox Swagger2（依赖为springfox-swagger2+springfox-swagger-ui）：需保证@ApiParam的导入路径为 springfox.documentation.annotations.ApiParam
• 若你使用的是SpringDoc OpenAPI3：应弃用@ApiParam，改用io.swagger.v3.oas.annotations.Parameter注解实现参数描述

2. Springfox与Spring Boot版本兼容问题

如果你的Spring Boot版本为2.6及以上，默认启用的PathPatternParser路径匹配策略和Springfox适配的AntPathMatcher不兼容，添加@ApiParam后触发参数解析阶段的路径校验错误，会直接过滤该接口。
解决方法：在application.properties/application.yml中添加如下配置即可：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

3. Springfox 3.0.0 已知BUG

Springfox 3.0.0版本存在参数解析缺陷，当@ApiParam和@NotNull等JSR-380参数校验注解同时标注在参数上时，会触发空指针异常导致接口加载失败。
解决方法：

• 降级Springfox版本到2.9.2
• 或者切换到更稳定的SpringDoc OpenAPI作为接口文档依赖

4. @ApiParam配置不规范

部分版本的Swagger要求@ApiParam必须显式设置value属性，缺少该属性时会被判定为无效参数导致接口跳过。你可以补充value属性后重试：

@GetMapping
@ApiOperation(value = "Get magazines by type")
public List<Magazine> getMagazines(@ApiParam(value = "查询的杂志类型", defaultValue = "TEST") @RequestParam @NotNull String type) {
    List<Magazine> response = service.getMagazines(type);
    return response;
}

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