Swagger占位符描述问题求助：参数重复显示且带短横线

1. 检查注解重复配置 #

• 确认Controller和Service层的参数是否重复添加了@ApiParam注解：如果Service层不需要暴露Swagger文档，直接移除Service方法参数上的@ApiParam，避免参数被重复解析。
• 检查@ApiParam的name或value属性，不要手动写入带短横线的名称，保持和代码中参数名一致（比如用userId而非user-id）。

2. 修改Swagger参数命名策略（SpringFox场景） #

自定义参数命名规则，禁止自动将驼峰式参数名转为短横线格式，创建配置类：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.project.controller")) // 仅扫描Controller层
                .paths(PathSelectors.any())
                .build();
    }

    // 强制返回原始参数名，不做格式转换
    @Bean
    public ParameterNamingStrategy parameterNamingStrategy() {
        return (parameter) -> parameter.getParameterName();
    }
}

3. 调整SpringDoc配置（OpenAPI 3场景） #

在application.yml中添加配置，禁用参数名的自动转换：

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
  # 保留原始参数名，不转为短横线格式
  default-param-name-pattern: original

4. 限制Swagger扫描范围 #

确保Swagger仅扫描Controller层，避免Service层参数被重复解析：

• 在Swagger配置的apis()方法中，明确指定Controller所在的包路径，比如RequestHandlerSelectors.basePackage("com.your.project.controller")。

最后清理应用缓存并重启，验证占位符是否显示正常。

内容的提问来源于stack exchange，提问作者Mario Cañas