feat: implement openapi merge task with openapi-generator (#379)

* feat: implement openapi merge task with openapi-generator

* set defaults on pom extension

* add missing dependency

Author: ndr-brt

buildSrc/build.gradle.kts

@@ -24,7 +24,9 @@ dependencies {
     implementation(libs.plugin.checksum)
     implementation(libs.plugin.publish)
     implementation(libs.plugin.swagger)
-    implementation(libs.plugin.openapi.merger) {
+    implementation(libs.plugin.openapi.generator)
+    implementation(libs.swagger.parser)
+    implementation(libs.plugin.openapi.merger) { // DEPRECATED
         constraints {
             implementation(libs.swagger.parser) {
                 because("OpenAPI merger plugin uses an old version that caused this issue: https://github.com/eclipse-edc/GradlePlugins/issues/183")

gradle/libs.versions.toml

@@ -13,6 +13,7 @@ jakarta-ws-rs = "4.0.0"
 jupiter = "5.13.4"
 mockito = "5.19.0"
 openapi-merger = "1.0.5"
+openapi-generator = "7.14.0"
 swagger = "2.2.26"
 swagger-parser = "2.1.33"
 
@@ -29,10 +30,12 @@ jetbrains-annotations = { module = "org.jetbrains:annotations", version.ref = "j
 jupiter-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "jupiter" }
 markdown-gen = { module = "net.steppschuh.markdowngenerator:markdowngenerator", version = "1.3.1.1" }
 mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito" }
+openapi-generator = { module = "org.openapitools:openapi-generator", version.ref = "openapi-generator" }
 plugin-publish = { module = "com.vanniktech:gradle-maven-publish-plugin", version = "0.34.0" }
 plugin-checksum = { module = "gradle.plugin.org.gradle.crypto:checksum", version = "1.4.0" }
 plugin-openapi-merger = { module = "com.rameshkp:openapi-merger-gradle-plugin", version.ref = "openapi-merger" }
 plugin-openapi-merger-app = { module = "com.rameshkp:openapi-merger-app", version.ref = "openapi-merger" }
+plugin-openapi-generator = { module = "org.openapitools:openapi-generator-gradle-plugin", version.ref = "openapi-generator" }
 plugin-swagger = { module = "io.swagger.core.v3:swagger-gradle-plugin", version.ref = "swagger" }
 swagger-parser = { module = "io.swagger.parser.v3:swagger-parser", version.ref = "swagger-parser" }
 

plugins/edc-build/build.gradle.kts

@@ -13,6 +13,10 @@ dependencies {
     implementation(libs.plugin.checksum)
     implementation(libs.plugin.publish)
     implementation(libs.plugin.swagger)
+    implementation(libs.openapi.generator)
+    implementation(libs.plugin.openapi.generator)
+    implementation(libs.swagger.parser)
+    // openapi-merger deprecated, will be removed
     implementation(libs.plugin.openapi.merger.app)
     implementation(libs.plugin.openapi.merger) {
         constraints {

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/EdcBuildBasePlugin.java

@@ -16,9 +16,17 @@
 package org.eclipse.edc.plugins.edcbuild;
 
 import org.eclipse.edc.plugins.edcbuild.extensions.BuildExtension;
+import org.eclipse.edc.plugins.edcbuild.plugins.ModuleNamesPlugin;
+import org.eclipse.edc.plugins.edcbuild.plugins.OpenApiMergerPlugin;
+import org.eclipse.edc.plugins.edcbuild.plugins.TestSummaryPlugin;
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
+import org.gradle.api.plugins.JavaLibraryPlugin;
+import org.gradle.api.plugins.JavaPlugin;
+import org.gradle.api.plugins.quality.CheckstylePlugin;
+import org.gradle.api.publish.maven.plugins.MavenPublishPlugin;
 import org.gradle.api.publish.maven.tasks.AbstractPublishToMaven;
+import org.gradle.crypto.checksum.ChecksumPlugin;
 import org.gradle.plugins.signing.Sign;
 
 import static java.util.List.of;
@@ -48,8 +56,7 @@ public void apply(Project target) {
         // register the extension(s)
         target.getExtensions().create("edcBuild", BuildExtension.class, target.getObjects());
 
-        // apply all plugins
-        target.getPlugins().apply(EdcBuildBasePlugin.class);
+        applyPlugins(target);
 
         target.getTasks().withType(AbstractPublishToMaven.class).configureEach(task -> {
             var signTasks = target.getTasks().withType(Sign.class);
@@ -82,7 +89,21 @@ public void apply(Project target) {
                     waitForPublishedArtifacts()
             ).forEach(c -> c.apply(project));
         });
+    }
+
+    private static void applyPlugins(Project target) {
+        var plugins = target.getPlugins();
 
+        plugins.apply(CheckstylePlugin.class);
+        plugins.apply(JavaLibraryPlugin.class);
+        plugins.apply(JavaPlugin.class);
+        plugins.apply(MavenPublishPlugin.class);
+        plugins.apply(TestSummaryPlugin.class);
 
+        if (target == target.getRootProject()) {
+            plugins.apply(ChecksumPlugin.class);
+            plugins.apply(OpenApiMergerPlugin.class);
+            plugins.apply(ModuleNamesPlugin.class);
+        }
     }
 }

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/EdcBuildPlugin.java

@@ -37,8 +37,6 @@
  */
 class MavenArtifactConvention implements EdcConvention {
 
-    private static final String PROJECT_URL = "https://projects.eclipse.org/projects/technology.edc";
-
     @Override
     public void apply(Project target) {
         target.afterEvaluate(project -> {
@@ -49,7 +47,7 @@ public void apply(Project target) {
             pubExt.getPublications().stream()
                     .filter(p -> p instanceof MavenPublication)
                     .map(p -> (MavenPublication) p)
-                    .peek(mavenPub -> mavenPub.pom(pom -> setPomInformation(pomExt, target, pom)))
+                    .peek(mavenPub -> mavenPub.pom(pom -> setPomInformation(pomExt, pom)))
                     .forEach(mavenPub -> {
                         var openapiFiles = target.getLayout().getBuildDirectory().getAsFile().get().toPath()
                                 .resolve("docs").resolve("openapi").toFile()
@@ -80,25 +78,23 @@ private void addArtifactIfExist(Project project, File location, MavenPublication
         }
     }
 
-    private static void setPomInformation(MavenPomExtension pomExt, Project project, MavenPom pom) {
-        // these properties are mandatory!
-        var projectName = pomExt.getProjectName().getOrElse(project.getName());
-        var description = pomExt.getDescription().getOrElse("edc :: " + project.getName());
-        var projectUrl = pomExt.getProjectUrl().getOrElse(PROJECT_URL);
+    private static void setPomInformation(MavenPomExtension pomExt, MavenPom pom) {
+        var projectName = pomExt.getProjectName().get();
+        var description = pomExt.getDescription().get();
+        var projectUrl = pomExt.getProjectUrl().get();
         pom.getName().set(projectName);
         pom.getDescription().set(description);
         pom.getUrl().set(projectUrl);
 
-        // we'll provide a sane default for these properties
         pom.licenses(l -> l.license(pl -> {
-            pl.getName().set(pomExt.getLicenseName().getOrElse("The Apache License, Version 2.0"));
-            pl.getUrl().set(pomExt.getLicenseUrl().getOrElse("http://www.apache.org/licenses/LICENSE-2.0.txt"));
+            pl.getName().set(pomExt.getLicenseName().get());
+            pl.getUrl().set(pomExt.getLicenseUrl().get());
         }));
 
         pom.developers(d -> d.developer(md -> {
-            md.getId().set(pomExt.getDeveloperId().getOrElse("mspiekermann"));
-            md.getName().set(pomExt.getDeveloperName().getOrElse("Markus Spiekermann"));
-            md.getEmail().set(pomExt.getDeveloperEmail().getOrElse("[email protected]"));
+            md.getId().set(pomExt.getDeveloperId().get());
+            md.getName().set(pomExt.getDeveloperName().get());
+            md.getEmail().set(pomExt.getDeveloperEmail().get());
         }));
 
         pom.scm(scm -> {

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/conventions/MavenArtifactConvention.java

@@ -25,7 +25,10 @@
 
 /**
  * Configures inputs and outputs for the OpenAPI merger plugin
+ *
+ * @deprecated will be removed together with openapi-merger
  */
+@Deprecated(since = "edc-build-1.0.0")
 class OpenApiMergerConvention implements EdcConvention {
 
     private static final String OPEN_API_VERSION = "3.0.1";

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/conventions/OpenApiMergerConvention.java

@@ -14,11 +14,28 @@
 
 package org.eclipse.edc.plugins.edcbuild.extensions;
 
+import org.gradle.api.Project;
 import org.gradle.api.provider.Property;
 
+import javax.inject.Inject;
+
 public abstract class MavenPomExtension {
+
+    private static final String PROJECT_URL = "https://projects.eclipse.org/projects/technology.edc";
     private String groupId = "org.eclipse.edc";
 
+    @Inject
+    public MavenPomExtension(Project project) {
+        getProjectName().convention(project.getName());
+        getDescription().convention("edc :: " + project.getName());
+        getProjectUrl().convention(PROJECT_URL);
+        getLicenseName().convention("The Apache License, Version 2.0");
+        getLicenseUrl().convention("http://www.apache.org/licenses/LICENSE-2.0.txt");
+        getDeveloperId().convention("mspiekermann");
+        getDeveloperName().convention("Markus Spiekermann");
+        getDeveloperEmail().convention("[email protected]");
+    }
+
     public abstract Property<String> getProjectName();
 
     public abstract Property<String> getDescription();

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/extensions/MavenPomExtension.java

@@ -21,7 +21,10 @@
 
 /**
  * Customization of the {@link OpenApiMergerTask}, which allows to pass in the input and output directories via command line.
+ *
+ * @deprecated please use mergeOpenApiSpec task
  */
+@Deprecated(since = "edc-build-1.0.0")
 public class MergeApiSpecByPathTask extends OpenApiMergerTask {
 
     public static final String NAME = "mergeApiSpec";

plugins/edc-build/src/main/java/org/eclipse/edc/plugins/edcbuild/plugins/MergeApiSpecByPathTask.java

@@ -0,0 +1,118 @@
+/*
+ *  Copyright (c) 2022 Microsoft Corporation
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Microsoft Corporation - initial API and implementation
+ *
+ */
+
+package org.eclipse.edc.plugins.edcbuild.plugins;
+
+import io.swagger.parser.OpenAPIParser;
+import io.swagger.v3.core.util.Yaml;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.parser.core.models.ParseOptions;
+import org.eclipse.edc.plugins.edcbuild.extensions.BuildExtension;
+import org.gradle.api.file.Directory;
+import org.gradle.api.model.ObjectFactory;
+import org.gradle.api.tasks.TaskAction;
+import org.gradle.api.tasks.options.Option;
+import org.jetbrains.annotations.NotNull;
+import org.openapitools.generator.gradle.plugin.tasks.GenerateTask;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Collections;
+import javax.inject.Inject;
+
+import static org.eclipse.edc.plugins.edcbuild.conventions.ConventionFunctions.requireExtension;
+
+/**
+ * Customization of the {@link GenerateTask}, which allows to pass in the input and output directories via command line.
+ */
+public class MergeOpenApiSpecTask extends GenerateTask {
+
+    public static final String NAME = "mergeOpenApiSpec";
+
+    private final Directory buildOpenapiFolder = getProject().getLayout().getBuildDirectory().get().dir("openapi");
+    private String infoTitle = getProject().getName();
+    private String infoDescription = "API documentation";
+    private String infoVersion = "0.0.0";
+    private Path output = buildOpenapiFolder.file("merged.yaml").getAsFile().toPath();
+
+    @Inject
+    public MergeOpenApiSpecTask(@NotNull ObjectFactory objectFactory) {
+        super(objectFactory);
+        getInputSpecRootDirectorySkipMerge().set(false);
+        getSkipValidateSpec().set(true);
+        getGeneratorName().set("openapi-yaml");
+        getOutputDir().set(buildOpenapiFolder.dir("generated").getAsFile().getAbsolutePath());
+    }
+
+    @Option(option = "inputDir", description = "Input directory where to look for partial specs. Required")
+    public void setInputDir(String inputDir) {
+        getInputSpecRootDirectory().set(inputDir);
+    }
+
+    @Option(option = "outputDir", description = "Output directory where the merged spec file will be stored. Optional.")
+    public void setOutputDir(String outputDirectory) {
+        getOutputDir().set(outputDirectory);
+    }
+
+    @Option(option = "output", description = "Output merged file path")
+    public void setOutput(String output) {
+        this.output = Path.of(output);
+    }
+
+    @Option(option = "infoTitle", description = "OpenAPI info.title value")
+    public void setInfoTitle(String infoTitle) {
+        this.infoTitle = infoTitle;
+    }
+
+    @Option(option = "infoDescription", description = "OpenAPI info.description value")
+    public void setInfoDescription(String infoDescription) {
+        this.infoDescription = infoDescription;
+    }
+
+    @Option(option = "infoVersion", description = "OpenAPI info.version value")
+    public void setInfoVersion(String infoVersion) {
+        this.infoVersion = infoVersion;
+    }
+
+    @TaskAction
+    public void task() throws IOException {
+        super.doWork();
+
+        var outputPath = Path.of(getOutputDir().get());
+        var spec = outputPath.resolve("openapi").resolve("openapi.yaml");
+        var parser = new OpenAPIParser();
+        var swaggerParseResult = parser.readLocation(spec.toString(), Collections.emptyList(), new ParseOptions());
+        var openApi = swaggerParseResult.getOpenAPI();
+        var info = new Info();
+        info.setTitle(infoTitle);
+        info.setDescription(infoDescription);
+        info.setVersion(infoVersion);
+        info.setLicense(createLicense());
+        openApi.setInfo(info);
+
+        Files.writeString(output, Yaml.pretty(openApi));
+    }
+
+    private License createLicense() {
+        var pom = requireExtension(getProject(), BuildExtension.class).getPom();
+        var license = new License();
+        license.setName(pom.getLicenseName().get());
+        license.setUrl(pom.getLicenseUrl().get());
+        return license;
+    }
+
+}
+