如何在Swagger中生成返回可下载文件（PDF）的API文档？

阿华AIGC实验室

2026-5-15

如何在Swagger中正确表示Spring文件下载接口的响应

我完全懂你的困扰——默认情况下Swagger会把InputStreamResource当成普通Java对象解析，展示它的JSON结构，但这完全不是文件下载接口该有的文档效果。其实只需要调整Swagger的注解，明确告诉它这个接口返回的是二进制文件流就行，下面是具体的解决方法：

核心解决方案：用`@ApiResponse`明确响应类型

你需要在@ApiResponse里通过@Content和@Schema注解，指定响应的媒体类型和文件格式，而非依赖Swagger自动解析返回值类型。

代码示例（适配Swagger 3.x/Springdoc）

修改后的接口注解应该是这样的：

@ApiOperation(value = "根据ID获取PDF文件")
@ApiResponses(value = {
    @ApiResponse(
        code = 200,
        message = "成功返回可下载的PDF文件",
        content = @Content(
            mediaType = "application/pdf",
            schema = @Schema(type = "string", format = "binary")
        )
    )
})
@GetMapping(produces = "application/pdf")
ResponseEntity<InputStreamResource> find(@PathVariable long id);

关键注解说明

@Content(mediaType = "application/pdf")：和接口produces属性保持一致，明确响应的媒体类型是PDF
@Schema(type = "string", format = "binary")：告诉Swagger这是一个二进制字符串（即文件流），这样Swagger UI就会生成一个下载按钮，而非展示InputStreamResource的JSON结构

可选优化：补充响应头说明

如果你的接口会返回Content-Disposition头部（用来指定文件名和下载方式），可以在注解里加上响应头的说明，让文档更完整：

@ApiResponse(
    code = 200,
    message = "成功返回可下载的PDF文件",
    content = @Content(
        mediaType = "application/pdf",
        schema = @Schema(type = "string", format = "binary")
    ),
    headers = {
        @Header(name = "Content-Disposition", description = "指定文件下载的文件名和方式，示例：attachment; filename=\"document.pdf\"", schema = @Schema(type = "string"))
    }
)

适配Swagger 2.x（Springfox）的写法

如果你还在使用Springfox版本的Swagger，写法略有调整，同样可以明确响应类型：

@ApiOperation(value = "根据ID获取PDF文件")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "成功返回PDF文件",
        responseHeaders = @ResponseHeader(name = "Content-Disposition", description = "文件下载头部", response = String.class),
        content = @Content(mediaType = "application/pdf", schema = @Schema(type = "string", format = "binary"))
    )
})
@GetMapping(produces = "application/pdf")
ResponseEntity<InputStreamResource> find(@PathVariable long id);