OpenAPI优先Gradle项目最优结构及代码生成方案咨询

一、推荐项目结构 #

采用多模块Gradle项目，将API规范、服务端、客户端分离，确保职责清晰且依赖关系明确：

root-project/
├── api-spec/          # 独立维护OpenAPI规范的子项目
│   ├── src/main/resources/
│   │   └── openapi.yml
│   └── build.gradle
├── server/            # Spring Boot服务端应用子项目
│   ├── build.gradle
│   └── src/
├── client/            # 可发布至Artifactory的Java客户端子项目
│   ├── build.gradle
│   └── src/
└── settings.gradle

在settings.gradle中注册子项目：

include ':api-spec', ':server', ':client'

二、技术挑战解决方案 #

1. OpenAPI规范的存放与引用 #

建议：将openapi.yml放在独立的api-spec子项目中，作为公共资源供服务端和客户端依赖，确保两者使用的规范完全一致。

配置api-spec子项目

该子项目仅负责托管规范文件，无需复杂逻辑，build.gradle配置如下：

plugins {
    id 'java'
    // 如需将规范发布到仓库供外部项目使用，可添加maven-publish插件
    id 'maven-publish'
}

sourceSets {
    main {
        resources {
            srcDirs = ['src/main/resources']
            include 'openapi.yml'
        }
    }
}

// 可选：发布规范到仓库
publishing {
    publications {
        maven(MavenPublication) {
            from components.java
        }
    }
}

服务端/客户端引用规范

在服务端和客户端的build.gradle中，先依赖api-spec子项目，再配置openApiGenerate任务的inputSpec：

// 添加子项目依赖
dependencies {
    implementation project(':api-spec')
}

// 配置生成任务时引用规范文件
openApiGenerate {
    inputSpec = project(':api-spec').sourceSets.main.resources.find { it.name == 'openapi.yml' }.absolutePath
    // 确保api-spec的资源处理任务优先执行
    dependsOn project(':api-spec').processResources
}

2. 服务端与客户端生成任务的分离与去冗余 #

不建议将两个生成任务放在同一子项目，分开配置在server和client子项目中，可避免代码混叠，同时通过配置参数禁用冗余代码生成。

服务端生成任务配置（仅生成Spring Boot骨架）

使用spring生成器，通过configOptions禁用客户端相关代码生成：

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'java'
    id 'org.openapi.generator' version '7.6.0'
}

openApiGenerate {
    generatorName = 'spring'
    inputSpec = project(':api-spec').sourceSets.main.resources.find { it.name == 'openapi.yml' }.absolutePath
    outputDir = "$buildDir/generated/openapi/server"
    apiPackage = 'com.example.api'
    modelPackage = 'com.example.model'
    configOptions = [
        interfaceOnly: 'true', // 仅生成API接口，自行实现业务逻辑
        useSpringBoot3: 'true',
        skipClient: 'true', // 核心参数：禁用客户端类生成
        generateApiTests: 'false',
        generateModelTests: 'false'
    ]
}

// 将生成的代码加入源码集，便于编译和开发
sourceSets.main.java.srcDir "$buildDir/generated/openapi/server/src/main/java"

客户端生成任务配置（生成可发布的Java客户端）

使用java或java-feign生成器，配置发布至Artifactory的规则：

plugins {
    id 'java'
    id 'org.openapi.generator' version '7.6.0'
    id 'maven-publish'
    id 'com.jfrog.artifactory' version '5.3.2'
}

openApiGenerate {
    generatorName = 'java-feign' // 可根据需求选择resttemplate、feign等客户端库
    inputSpec = project(':api-spec').sourceSets.main.resources.find { it.name == 'openapi.yml' }.absolutePath
    outputDir = "$buildDir/generated/openapi/client"
    apiPackage = 'com.example.client.api'
    modelPackage = 'com.example.client.model'
    configOptions = [
        dateLibrary: 'java8',
        library: 'feign',
        generateApiTests: 'false',
        generateModelTests: 'false'
    ]
}

sourceSets.main.java.srcDir "$buildDir/generated/openapi/client/src/main/java"

// 配置Artifactory发布
artifactory {
    contextUrl = 'https://your-artifactory-instance-url'
    publish {
        repository {
            repoKey = 'libs-release-local' // 根据实际仓库选择
            username = System.getenv('ARTIFACTORY_USER')
            password = System.getenv('ARTIFACTORY_PWD')
        }
        defaults {
            publications('maven')
        }
    }
}

// 配置Maven发布信息
publishing {
    publications {
        maven(MavenPublication) {
            from components.java
            groupId = 'com.example'
            artifactId = 'openapi-client'
            version = '1.0.0'
        }
    }
}

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