refactor(model-server): merge OpenAPI specs before using them

This commit makes the model-server-openapi folder a module again, which
is now responsible for merging the individual OpenAPI specification
files into a single one that's then used inside the build and for the
SwaggerUI of the model-server. This has several benefits:

* The SwaggerUI configuration and usage is easier as we present a
  single, combined API with a good overview under a single URL.
* The duplicated generated of shared models such as the Problem type is
  prevented as the merging deduplicates the data type.

Implementing merging is implemented with redocly, which was the only
tool I could find for this tasks that worked. The model-server-openapi
contains a decorator plugin for redocly that, as part of the merge
process, prepends the server URL paths to routes so that URLs are
correct in the merged result specification.

The different specifications we maintain had a few duplicated response
names that caused issues when merging. These duplications were resolved
by renaming some instances of them.

To properly categorize the different APIs in the SwaggerUI for the user,
tags were added everywhere in the specifications.

I could also get rid of several required imports by generating the
source code into the same package that's also used for the API
implementation.

Author: languitar

.gitignore

@@ -7,7 +7,7 @@
 *.iml
 kotlin_gen
 /version.txt
-/node_modules
+**/node_modules/
 **/.ideaconfig
 **/.mpsconfig
 .kotlin

build.gradle.kts

@@ -51,7 +51,7 @@ fun computeVersion(): Any {
 
 dependencies {
     // Generate a combined coverage report
-    project.subprojects.forEach {
+    project.subprojects.filterNot { it.name in setOf("model-server-openapi") }.forEach {
         kover(it)
     }
 }
@@ -62,7 +62,9 @@ subprojects {
     val subproject = this
     apply(plugin = "maven-publish")
     apply(plugin = "org.jetbrains.dokka")
-    apply(plugin = "org.jetbrains.kotlinx.kover")
+    if (subproject.name !in setOf("model-server-openapi")) {
+        apply(plugin = "org.jetbrains.kotlinx.kover")
+    }
 
     version = rootProject.version
     group = rootProject.group

model-server-openapi/build.gradle.kts

@@ -0,0 +1,68 @@
+import com.github.gradle.node.npm.task.NpxTask
+
+plugins {
+    base
+    alias(libs.plugins.node)
+}
+
+description = "OpenAPI specification for the model-server"
+
+val specDir = layout.projectDirectory.dir("specifications")
+
+val bundleDir = layout.buildDirectory.dir("bundled").get()
+
+val joinedFile = layout.buildDirectory.file("model-server.yaml").get()
+
+// We bundle the specs to apply the decorator that prepends the server path to each route.
+val bundleSpecs = tasks.register<NpxTask>("bundleSpecs") {
+    description = "preprocesses OpenAPI specifications before joining them"
+
+    dependsOn(tasks.getByName("npmInstall"))
+
+    inputs.dir(specDir)
+
+    outputs.cacheIf { true }
+    outputs.dir(bundleDir)
+
+    command.set("redocly")
+    args.addAll("bundle", "--output", bundleDir.toString())
+}
+
+// We combine all specifications into one to deduplicate things like the Problem type
+val joinSpecs = tasks.register<NpxTask>("joinSpecs") {
+    description = "combines all OpenAPI specifications into a single one"
+
+    dependsOn(tasks.getByName("npmInstall"))
+    dependsOn(bundleSpecs)
+
+    inputs.dir(bundleDir)
+
+    outputs.cacheIf { true }
+    outputs.file(joinedFile)
+
+    command.set("redocly")
+    args.addAll("join", "--output", joinedFile.toString())
+    // We sort the v2 file first because it determines the meta-data of the generated joined file.
+    // This list of files needs to be kept in sync with the contents of redocly.yaml. We cannot dynamically detect the
+    // files generated by redocly here as NPM argas can only be passed in the configuration phase of Gradle. At that
+    // point in time, no files have been generated yet on fresh builds.
+    args.addAll(
+        listOf(
+            "model-server-v2.yaml",
+            "model-server-v1.yaml",
+            "model-server-operative.yaml",
+        ).map { bundleDir.file(it).toString() },
+    )
+}
+
+// This provides the resulting joined OpenAPI specification to the model-server project to be declared as a dependency.
+// Cf. https://docs.gradle.org/current/userguide/cross_project_publications.html#cross_project_publications
+val openApiSpec by configurations.creating {
+    isCanBeConsumed = true
+    isCanBeResolved = false
+}
+artifacts {
+    add(openApiSpec.name, joinedFile) {
+        builtBy(joinSpecs)
+    }
+}