Gradle配置自定义OpenApiCustomiser时依赖解析失败求助

问题根源 #

你遇到的两个错误本质是同一个问题：buildscript的classpath和项目主代码的classpath是完全隔离的。直接把自定义的MyOpenApiCustomiser加到buildscript依赖里，Gradle找不到未编译的项目代码；乱删版本号则会导致依赖声明格式非法，触发IllegalDependencyNotation。

正确配置步骤 #

1. 优先用buildSrc托管自定义类 #

这是Gradle官方推荐的方式，buildSrc目录下的代码会自动被编译并加入buildscript的classpath，无需额外配置：

• 在项目根目录创建buildSrc/src/main/java/[你的包路径]/MyOpenApiCustomiser.java，把自定义类移到这里
• 直接在swagger插件配置里引用类的全限定名即可，比如：

swagger {
    apiSource {
        openApiCustomisers = ["com.yourpackage.MyOpenApiCustomiser"]
    }
}

2. 若需在主项目中保留自定义类 #

如果不想用buildSrc，需要先编译主项目代码，再将编译产物引入buildscript：

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        // 必须指定swagger-core的正确版本，和项目依赖保持一致
        classpath "io.swagger.core.v3:swagger-core:2.2.15"
        // 引入主项目编译后的类文件
        classpath files(project.sourceSets.main.output.classesDirs)
    }
}

// 强制swagger任务依赖编译任务，确保类已生成
tasks.named("swaggerGenerate") {
    dependsOn tasks.named("compileJava")
}

注意：这种方式需要先执行compileJava再执行swagger任务，否则会出现类找不到的问题。

3. 避免IllegalDependencyNotation异常 #

这个异常是依赖声明格式错误导致的：

• 第三方依赖（如swagger-core）必须指定完整的groupId:artifactId:version格式，不能省略版本号
• 引用本地类文件必须用files()、project()等合法的依赖符号，不能直接写类名或不完整的依赖字符串

替代方案：跳过Gradle插件，直接用Swagger Java API #

如果插件配置太繁琐，可以直接在项目代码中生成OpenAPI文档，灵活性更高：

1. 确保项目依赖中包含swagger-core：

dependencies {
    implementation "io.swagger.core.v3:swagger-core:2.2.15"
}

2. 编写生成类：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.core.util.Json;
import java.io.FileWriter;
import java.io.IOException;

public class OpenApiGenerator {
    public static void main(String[] args) throws IOException {
        OpenAPI openAPI = new OpenAPI();
        // 应用自定义配置
        new MyOpenApiCustomiser().customise(openAPI);
        // 写入JSON文件
        try (FileWriter writer = new FileWriter("build/openapi.json")) {
            writer.write(Json.pretty(openAPI));
        }
    }
}

3. 在Gradle中添加执行任务：

tasks.register("generateOpenApi", JavaExec) {
    mainClass = "com.yourpackage.OpenApiGenerator"
    classpath = sourceSets.main.runtimeClasspath
}

执行./gradlew generateOpenApi即可生成文档。

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