Springfox：@ApiResponse中的@ResponseHeader未在Swagger UI中渲染

这其实是Springfox的一个已知小坑，不是你配置错了——而是注解层级的处理逻辑差异导致的。全局响应头（通过Docket配置）和方法级@ApiResponse里的响应头，在Springfox的解析流程中走的是不同路径，旧版本甚至存在解析bug。

下面是几个经过验证的解决方案，按优先级尝试：

1. 升级Springfox版本 #

部分旧版本（比如2.9.x及更早）确实存在方法级@ResponseHeader不被Swagger UI渲染的问题。升级到2.10.0或更高的稳定版本，很多时候能直接解决这个问题。

2. 显式指定response属性 #

如果你的@ApiResponse没有指定response属性（即使接口不需要返回实体），Springfox可能会跳过响应头的解析。试试给注解加上response = Void.class（或者你实际返回的类型）：

@ApiResponses(value = { 
    @ApiResponse(code = 200, message = "Options for the endpoint", 
                response = Void.class, // 显式指定响应类型
                responseHeaders = {@ResponseHeader(name = "Allow", description = "Verbs allowed")})
})

3. 结合全局响应头配置补全 #

如果升级版本和指定response都没用，可以针对这个特定接口的状态码，在Docket里添加全局响应头配置，和方法级注解配合使用：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.package"))
            .paths(PathSelectors.any())
            .build()
            // 针对OPTIONS请求的200状态码添加全局响应头
            .globalResponses(HttpMethod.OPTIONS, Arrays.asList(
                new ResponseBuilder()
                    .code("200")
                    .description("Options for the endpoint")
                    .header("Allow", "Verbs allowed")
                    .build()
            ));
}

4. 检查Swagger UI版本兼容性 #

确保你的Swagger UI版本和Springfox版本匹配：Springfox 2.x对应Swagger UI 2.x，Springfox 3.x对应Swagger UI 3.x。版本不匹配也可能导致渲染异常。

补充说明 #

这个问题在Springfox社区讨论中被多次提及，核心原因是方法级的@ResponseHeader在解析时没有被正确关联到对应的响应模型中，而全局配置的响应头是直接注入到Swagger的全局响应定义里，所以能被UI正确识别。

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