Spring Boot 2中如何为Swagger Codegen处理org.springframework.core.io.Resource

我之前刚好折腾过一模一样的Spring Boot 2多项目架构——一个后端REST API服务负责核心业务逻辑（还包含文件下载的端点），另一个Web项目靠Swagger Codegen自动生成API调用类来渲染页面并调用后端接口。结合这个场景，我整理了几个关键的实践点，应该能帮到你：

1. 先把后端文件下载端点的Swagger规范做对 #

你的ResourceController里的文件下载端点，得符合Swagger能识别的格式，这样Codegen才能生成正确的调用类。举个实际的代码例子：

@RestController
@RequestMapping("/api/resources")
public class ResourceController {

    @GetMapping(value = "/download/{fileId}", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
    public ResponseEntity<Resource> downloadFile(@PathVariable String fileId) {
        // 这里替换成你实际的文件获取逻辑，比如从本地存储、OSS或者数据库读取
        Resource fileResource = new FileSystemResource("/your/storage/path/" + fileId);
        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + fileResource.getFilename() + "\"")
                .body(fileResource);
    }
}

这里有两个关键细节：

• 一定要指定produces = MediaType.APPLICATION_OCTET_STREAM_VALUE，明确告诉Swagger这是二进制流响应
• 正确设置Content-Disposition响应头，确保前端能识别这是需要下载的文件，而不是直接在浏览器打开

2. 调整Swagger Codegen配置适配二进制文件 #

Web项目里用Swagger Codegen的时候，得改下配置，让它能正确处理二进制响应，不然生成的API类可能只会返回字符串或者乱码。

以Maven插件为例的配置调整 #

在Web项目的pom.xml里，给Swagger Codegen插件加上这些参数：

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.34</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api-spec.yaml</inputSpec>
                <language>java</language>
                <configOptions>
                    <library>spring-boot</library>
                    <useOptional>true</useOptional>
                    <!-- 重点：开启二进制支持，这是处理文件下载的关键 -->
                    <enableBinarySupport>true</enableBinarySupport>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

用生成的API类调用文件下载端点 #

配置好之后生成的API类，会自动处理二进制流，你直接在Web项目的服务或者控制器里调用就行，比如：

@Service
public class ResourceService {

    private final ResourceApi resourceApi;

    // 用构造注入的方式引入生成的API类
    public ResourceService(ResourceApi resourceApi) {
        this.resourceApi = resourceApi;
    }

    public ResponseEntity<Resource> downloadFile(String fileId) {
        // 调用生成的带HttpInfo的方法，直接拿到包含文件流和响应头的ResponseEntity
        return resourceApi.downloadFileWithHttpInfo(fileId);
    }
}

3. Web项目前端页面处理文件下载 #

在Web项目的页面里，你可以通过后端转发的方式触发下载，比如用Thymeleaf的示例：

<a th:href="@{/web/download/{fileId}(fileId=${fileId})}" download>点击下载文件</a>

对应的Web项目控制器代码：

@Controller
@RequestMapping("/web/download")
public class WebDownloadController {

    private final ResourceService resourceService;

    public WebDownloadController(ResourceService resourceService) {
        this.resourceService = resourceService;
    }

    @GetMapping("/{fileId}")
    public ResponseEntity<Resource> handleFileDownload(@PathVariable String fileId) {
        // 直接转发到后端API的结果，前端就能触发下载了
        return resourceService.downloadFile(fileId);
    }
}

几个常见的坑要注意 #

• 如果生成的API类没返回二进制流，先检查Swagger规范里有没有正确定义produces: application/octet-stream
• 要是下载的文件损坏，看看后端有没有过滤器或者拦截器偷偷修改了文件流
• 跨域问题：如果两个项目跑在不同端口，记得给API服务器配置CORS，允许Web项目的域名访问

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