fix(openapi): make API its own gradle subproject

If the openAPI will be out basis for provided endpoints, we will respectively need the YAMLs and generated artifacts in several places. Compiling everything in the model-server is quite a lot of code which is now isolated in its own subproject.

Author: nkoester

api/build.gradle.kts

@@ -0,0 +1,111 @@
+import org.openapitools.generator.gradle.plugin.tasks.GenerateTask
+
+plugins {
+    kotlin("jvm")
+    kotlin("plugin.serialization")
+    alias(libs.plugins.openapi.generator)
+}
+
+description = "OpenAPI specifications for modelix components"
+
+defaultTasks.add("build")
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(11))
+    }
+}
+
+dependencies {
+    implementation(kotlin("stdlib"))
+    implementation(project(":model-api"))
+    implementation(project(":model-server-api"))
+
+    implementation(libs.google.gson)
+
+    implementation(libs.ktor.server.core)
+    implementation(libs.ktor.server.resources)
+}
+
+// OpenAPI integration
+val basePackage = project.group.toString()
+val openAPIgenerationPath = "${project.layout.buildDirectory.get()}/generated/openapi"
+
+// Pairs of the different OpenAPI files we use. Each pair must have its own 'category' as first argument as these
+// are used to generate corresponding packages
+val openApiFiles = listOf(
+    "public" to "model-server",
+    "operative" to "model-server-operative",
+    "light" to "model-server-light",
+    "html" to "model-server-html",
+    "deprecated" to "model-server-deprecated",
+)
+
+// generate tasks for each OpenAPI file
+openApiFiles.forEach {
+    val targetTaskName = "openApiGenerate-${it.second}"
+    val targetPackageName = "$basePackage.api.${it.first}"
+    val outputPath = "$openAPIgenerationPath/${it.first}"
+    tasks.register<GenerateTask>(targetTaskName) {
+        // we let the Gradle OpenAPI generator plugin build data classes and API interfaces based on the provided
+        // OpenAPI specification. That way, the code is forced to stay in sync with the API specification.
+        generatorName.set("kotlin-server")
+        inputSpec.set(layout.projectDirectory.dir("openapi/specifications").file("${it.second}.yaml").toString())
+        outputDir.set(outputPath)
+        packageName.set(targetPackageName)
+        apiPackage.set(targetPackageName)
+        modelPackage.set(targetPackageName)
+        // We use patched mustache so that only the necessary parts (i.e. resources and models)
+        // are generated. additionally we patch the used serialization framework as the `ktor` plugin
+        // uses a different one than we do in the model-server. The templates are based on
+        // https://github.com/OpenAPITools/openapi-generator/tree/809b3331a95b3c3b7bcf025d16ae09dc0682cd69/modules/openapi-generator/src/main/resources/kotlin-server
+        templateDir.set("$projectDir/openapi/templates")
+        configOptions.set(
+            mapOf(
+                // we use the ktor generator to generate server side resources and model (i.e. data classes)
+                "library" to "ktor",
+                // the generated artifacts are not built independently, thus no dedicated build files have to be generated
+                "omitGradleWrapper" to "true",
+                // the path to resource generation we need
+                "featureResources" to "true",
+                // disable features we do not use
+                "featureAutoHead" to "false",
+                "featureCompression" to "false",
+                "featureHSTS" to "false",
+                "featureMetrics" to "false",
+            ),
+        )
+        // generate only Paths and Models - only this set will produce the intended Paths.kt as well as the models
+        // the openapi generator is generally very picky and configuring it is rather complex
+        globalProperties.putAll(
+            mapOf(
+                "models" to "",
+                "apis" to "",
+                "supportingFiles" to "Paths.kt",
+            ),
+        )
+    }
+
+    // Ensure that the OpenAPI generator runs before starting to compile
+    tasks.named("processResources") {
+        dependsOn(targetTaskName)
+    }
+    tasks.named("compileKotlin") {
+        dependsOn(targetTaskName)
+    }
+    tasks.named("runKtlintCheckOverMainSourceSet") {
+        dependsOn(targetTaskName)
+    }
+
+    // do not apply ktlint on the generated files
+    ktlint {
+        filter {
+            exclude {
+                it.file.toPath().toAbsolutePath().startsWith(outputPath)
+            }
+        }
+    }
+
+    // add openAPI generated artifacts to the sourceSets
+    sourceSets["main"].kotlin.srcDir("$outputPath/src/main/kotlin")
+}

api/model-server-deprecated.yaml renamed to api/openapi/specifications/model-server-deprecated.yaml

@@ -0,0 +1,36 @@
+# WARNING - EXPERIMENTAL
+# This file was auto generated from the existing API using an IntelliJ plugin,
+# see https://www.jetbrains.com/help/idea/openapi.html#generate_openapi
+#
+# Manual changes were done for this 'spec' to work in-place with the
+# model-server for now. A lot of changes were done and are still necessary
+# to make this OpenAPI a viable artifact. It will most likely be split
+# into multiple OpenAPI files.
+
+openapi: "3.0.3"
+
+info:
+  title: "model-server operative API"
+  description: "modelix operative API"
+  version: "1.0.0"
+
+servers:
+  - url: '/'
+    description: model-server
+
+paths:
+  /metrics:
+    get:
+      operationId: getMetrics
+      responses:
+        "200":
+          $ref: '#/components/responses/200'
+
+components:
+  responses:
+    "200":
+      description: OK
+      content:
+        text/plain:
+          schema:
+            type: string

api/model-server-html.yaml renamed to api/openapi/specifications/model-server-html.yaml

@@ -553,12 +553,6 @@ paths:
           $ref: '#/components/responses/200'
         "404":
           $ref: '#/components/responses/404'
-  /metrics:
-    get:
-      operationId: getMetrics
-      responses:
-        "200":
-          $ref: '#/components/responses/200'
 components:
   responses:
     "200":

api/model-server-light.yaml renamed to api/openapi/specifications/model-server-light.yaml

@@ -0,0 +1,24 @@
+package {{packageName}}
+
+import io.ktor.server.application.*
+import io.ktor.http.*
+{{#featureResources}}
+import io.ktor.server.resources.*
+{{/featureResources}}
+
+import io.ktor.server.routing.*
+
+fun Application.main() {
+{{#generateApis}}
+    install(Routing) {
+    {{#apiInfo}}
+    {{#apis}}
+    {{#operations}}
+        {{classname}}()
+    {{/operations}}
+    {{/apis}}
+    {{/apiInfo}}
+    }
+
+{{/generateApis}}
+}

api/openapi/specifications/model-server-operative.yaml

@@ -0,0 +1,30 @@
+{{>licenseInfo}}
+package {{packageName}}
+
+import io.ktor.resources.*
+import kotlinx.serialization.*
+{{#imports}}import {{import}}
+{{/imports}}
+
+{{#apiInfo}}
+object Paths {
+{{#apis}}
+{{#operations}}
+    {{#operation}}
+    /**{{#summary}}
+     * {{.}}{{/summary}}
+     * {{unescapedNotes}}
+     {{#allParams}}* @param {{paramName}} {{description}} {{^required}}(optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}
+     {{/allParams}}*/
+    {{#hasParams}}
+    @Serializable @Resource("{{path}}") class {{operationId}}({{#allParams}}val {{paramName}}: {{{dataType}}}{{^required}}? = null{{/required}}{{#required}}{{#isNullable}}?{{/isNullable}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
+    {{/hasParams}}
+    {{^hasParams}}
+    @Serializable @Resource("{{path}}") class {{operationId}}
+    {{/hasParams}}
+
+    {{/operation}}
+{{/operations}}
+{{/apis}}
+}
+{{/apiInfo}}

api/model-server.yaml renamed to api/openapi/specifications/model-server.yaml

@@ -0,0 +1,43 @@
+{{>licenseInfo}}
+package {{apiPackage}}
+
+import com.google.gson.Gson
+import io.ktor.http.*
+import io.ktor.server.application.*
+import io.ktor.server.response.*
+{{#featureResources}}
+import {{packageName}}.Paths
+import io.ktor.server.resources.options
+import io.ktor.server.resources.get
+import io.ktor.server.resources.post
+import io.ktor.server.resources.put
+import io.ktor.server.resources.delete
+import io.ktor.server.resources.head
+import io.ktor.server.resources.patch
+{{/featureResources}}
+import io.ktor.server.routing.*
+{{#imports}}import {{import}}
+{{/imports}}
+
+{{#operations}}
+fun Route.{{classname}}() {
+    val gson = Gson()
+    val empty = mutableMapOf<String, Any?>()
+
+{{#operation}}
+    {{^featureResources}}
+    route("{{path}}") {
+        {{#lambda.lowercase}}{{httpMethod}}{{/lambda.lowercase}} {
+            {{#lambda.indented_12}}{{>libraries/ktor/_api_body}}{{/lambda.indented_12}}
+        }
+    }
+    {{/featureResources}}
+    {{#featureResources}}
+    {{#lambda.lowercase}}{{httpMethod}}{{/lambda.lowercase}}<Paths.{{operationId}}> {
+        {{#lambda.indented_8}}{{>libraries/ktor/_api_body}}{{/lambda.indented_8}}
+    }
+    {{/featureResources}}
+
+{{/operation}}
+}
+{{/operations}}

api/openapi/templates/AppMain.kt.mustache

@@ -0,0 +1,16 @@
+import kotlinx.serialization.Serializable
+
+/**
+ * {{{description}}}
+{{#vars}}
+ * @param {{{name}}} {{{description}}}
+{{/vars}}
+ */
+@Serializable
+data class {{classname}}(
+{{#requiredVars}}
+{{>data_class_req_var}}{{^-last}},
+{{/-last}}{{/requiredVars}}{{#hasRequired}}{{#hasOptional}},
+{{/hasOptional}}{{/hasRequired}}{{#optionalVars}}{{>data_class_opt_var}}{{^-last}},
+{{/-last}}{{/optionalVars}}
+)