Spring Boot+Gradle环境下从Swagger OpenAPI生成RestTemplate客户端存根问询

1. 替换生成器目标为Java RestTemplate客户端 #

你之前选择的spring生成目标是用来生成服务端控制器的，要生成客户端存根直接用OpenAPI Generator内置的java语言目标，指定依赖库为resttemplate即可，原生支持生成完整的接口、DTO、RestTemplate实现类，不需要手动编写接口实现代码。

2. 调整Gradle配置 #

修改配置调整输出路径、关闭多余文件生成，同时将生成代码自动加入项目编译类路径：

apply plugin: 'org.hidetake.swagger.generator'
apply plugin: 'java'

dependencies {
    // 保留OpenAPI Generator即可，功能兼容性更好
    swaggerCodegen 'org.openapitools:openapi-generator-cli:6.6.0'
    // 生成的客户端需要的基础依赖，直接加入项目编译依赖
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'com.fasterxml.jackson.core:jackson-databind'
}

swaggerSources {
    remoteservice {
        inputFile = file("${project.rootDir}/gradle/swagger-remoteservice.json")
        code {
            language = 'java'
            // 输出到Spring Boot项目标准的generated源码目录
            outputDir = file("${buildDir}/generated/sources/swagger-client/remoteservice")
            configOptions = [
                library: 'resttemplate', // 指定用RestTemplate实现客户端
                dateLibrary: 'java8', // 日期类使用java.time包
                serializationLibrary: 'jackson',
                interfaceOnly: 'false', // 生成完整实现类，不是只生成接口
                invokerPackage: 'com.yourcompany.remoteservice.client', // 替换为你项目的实际包名
                apiPackage: 'com.yourcompany.remoteservice.client.api',
                modelPackage: 'com.yourcompany.remoteservice.client.dto',
                hideGenerationTimestamp: 'true', // 避免时间戳变化导致Gradle缓存失效
                generatePom: 'false', // 关闭多余项目文件生成
                generateGradleProject: 'false',
                generateBuilders: 'true'
            ]
            // 只保留需要的文件，过滤掉启动类、测试类等多余内容
            components {
                models = true
                apis = true
                supportingFiles = ['ApiClient.java', 'RestTemplateErrorHandler.java', 'Configuration.java']
            }
        }
    }
}

// 自动将生成的代码加入编译类路径
sourceSets.main.java.srcDir swaggerSources.remoteservice.code.outputDir
// 保证编译前先执行代码生成任务
compileJava.dependsOn swaggerSources.remoteservice.code

3. 生成代码的使用方式 #

生成的代码已经封装了所有请求拼接、参数处理、响应反序列化逻辑，只需要做基础配置即可直接使用：

@Configuration
public class RemoteServiceConfig {
    @Bean
    public ApiClient remoteServiceApiClient(RemoteServiceProperties properties) {
        ApiClient apiClient = new ApiClient(new RestTemplateBuilder()
                // 此处可自定义授权拦截器、超时、重试等配置
                .build());
        apiClient.setBasePath(properties.getUrl());
        // 统一配置全局请求头，比如授权token
        apiClient.addDefaultHeader("Authorization", "Bearer " + properties.getAccessToken());
        return apiClient;
    }

    // 直接注册生成的API实现类为Bean，业务代码可直接注入使用
    @Bean
    public ItemApi itemApi(ApiClient remoteServiceApiClient) {
        return new ItemApi(remoteServiceApiClient);
    }
}

4. 适配特殊需求的优化项 #

• 整个生成过程完全基于本地的swagger.json文件，不需要访问远端服务，满足离线构建要求，同时插件原生支持Gradle输入缓存，只要swagger.json没有变动就不会重复执行生成任务
• 生成的代码不会包含控制器类，如果你担心被Spring自动扫描，把生成代码的包路径加入@ComponentScan的排除列表即可，所有API Bean手动在配置类注册，不会出现意外加载的问题
• 如果生成的代码逻辑不符合你的定制需求，可以自行编写Mustache模板覆盖官方内置模板，在configOptions中添加templateDirectory: "${project.rootDir}/gradle/swagger-templates"指定模板路径即可自定义生成逻辑

内容的提问来源于stack exchange，提问作者usr-local-ΕΨΗΕΛΩΝ