如何从源码为Spring Boot微服务生成Rest客户端API并打包为jar

不需要依赖运行时生成API文档的组件，可通过Gradle插件在构建阶段全自动化完成API规约生成、Rest客户端代码生成、客户端jar打包发布全流程，完美适配K8s微服务CI/CD自动化管理场景。

核心实现逻辑 #

整体流程全部在服务提供方的Spring Boot项目构建阶段完成，无需启动服务，无需人工介入：

• 第一步：通过Gradle插件扫描服务端的Spring Web注解，静态生成OpenAPI 3.0接口规约文件
• 第二步：基于生成的OpenAPI规约，自动生成强类型Rest客户端代码，支持FeignClient、WebClient、RestTemplate等多种常用客户端风格
• 第三步：将生成的客户端代码打包为独立jar，自动发布到内部私有Maven仓库，调用方直接依赖即可使用，无需手动编写调用逻辑

关键Gradle配置示例 #

所有配置均在服务提供方的build.gradle中完成，不需要修改业务代码

1. 引入所需插件 #

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
    // 用于生成OpenAPI规约，也可替换为完全静态扫描的swagger-gradle-plugin
    id 'org.springdoc.openapi-gradle-plugin' version '1.7.0'
    // 用于根据OpenAPI规约生成Rest客户端代码
    id 'org.openapi.generator' version '7.2.0'
    // 用于将客户端jar发布到私有Maven仓库
    id 'maven-publish'
}

2. 配置OpenAPI规约生成规则 #

openApi {
    outputDir = file("${buildDir}/openapi")
    outputFileName = "api-spec.json"
    // 构建阶段自动启动临时轻量上下文生成规约，完成后自动销毁，不影响CI流程
    waitTimeInSeconds = 30
}

如果不需要启动任何临时上下文，可替换为io.swagger.core.v3:swagger-gradle-plugin纯静态扫描源码生成规约，无任何运行时开销。

3. 配置Rest客户端生成规则（以FeignClient为例） #

openApiGenerate {
    generatorName = "spring"
    inputSpec = "${buildDir}/openapi/api-spec.json"
    outputDir = "${buildDir}/generated/client"
    // 自定义客户端代码的包名，避免和其他服务冲突
    apiPackage = "com.yourorg.yourapp.client.api"
    modelPackage = "com.yourorg.yourapp.client.model"
    configOptions = [
        interfaceOnly: "true",
        feign: "true",
        openApiNullable: "false",
        useSpringBoot3: "true"
    ]
}

4. 配置任务依赖和打包发布规则 #

// 串起构建流程：生成规约→生成客户端代码→编译打包
compileJava.dependsOn openApiGenerate
openApiGenerate.dependsOn openApi

// 打包时仅包含生成的客户端代码，排除服务端业务逻辑，生成独立的客户端jar
jar {
    from sourceSets.main.java
    include 'com/yourorg/yourapp/client/**'
    archiveClassifier = 'client'
}

// 配置自动发布到内部私有Maven仓库
publishing {
    publications {
        mavenJava(MavenPublication) {
            artifact jar
        }
    }
    repositories {
        maven {
            url = "http://你的内部Maven仓库地址/releases"
            credentials {
                // 账号密码从CI环境变量读取，避免硬编码
                username = System.getenv("MAVEN_USERNAME")
                password = System.getenv("MAVEN_PASSWORD")
            }
        }
    }
}

CI/CD集成方案 #

• 每次服务提供方的API代码合并到主干分支时，CI流水线自动执行./gradlew build publish命令，全自动生成新版本客户端jar并发布到私有仓库
• 服务调用方只需要在build.gradle中引入对应版本的客户端依赖，加上@EnableFeignClients(basePackages = "com.yourorg.yourapp.client")注解，即可直接注入客户端实例调用接口
• 接口出现不兼容变更时，会在构建阶段触发校验报错，提前暴露问题，避免运行时通信故障

方案优势 #

• 全流程无需人工介入，完全适配CI/CD自动化管理要求
• 生成的客户端为强类型代码，编译期即可校验参数、返回值是否匹配，避免运行时调用错误
• API变更统一由服务提供方维护，调用方无需手动同步代码，大幅降低K8s集群内微服务通信的维护成本

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