(fix) Umbau zu SCS

### 1.1 OpenAPI-Dokumentation implementieren - Swagger/OpenAPI in bestehenden Ktor-Diensten integrieren - Zentrale API-Dokumentationsseite im API-Gateway erstellen - CI/CD-Pipeline um automatische API-Dokumentationsgenerierung erweitern - Entwickler-Guidelines für API-Dokumentation erstellen
2025-07-21 13:45:58 +02:00
parent 77953c18f6
commit 81e40e70fc
13 changed files with 3192 additions and 72 deletions
@@ -1,6 +1,101 @@
 plugins {
    alias(libs.plugins.kotlin.multiplatform)
    alias(libs.plugins.kotlin.serialization)
+    id("org.openapi.generator") version "7.3.0" // Updated to latest version
+}
+
+// Get project version for documentation versioning
+val projectVersion = project.version.toString()
+
+// Configure OpenAPI Generator
+openApiGenerate {
+    generatorName.set("html2")
+    inputSpec.set("$projectDir/src/jvmMain/resources/openapi/documentation.yaml")
+    outputDir.set("$projectDir/build/generated-docs")
+
+    // Configure HTML2 generator options
+    configOptions.set(mapOf(
+        "infoUrl" to "https://meldestelle.at",
+        "infoEmail" to "support@meldestelle.at",
+        "title" to "Meldestelle API Documentation v$projectVersion"
+    ))
+
+    // Validate OpenAPI specification before generation
+    validateSpec.set(true)
+}
+
+// Task to validate OpenAPI specification
+tasks.register("validateOpenApi") {
+    group = "documentation"
+    description = "Validates the OpenAPI specification"
+
+    doLast {
+        // Use the OpenAPI Generator's validate task
+        tasks.named("openApiValidate").get().actions.forEach { action ->
+            action.execute(tasks.named("openApiValidate").get())
+        }
+        println("OpenAPI specification validated successfully")
+    }
+}
+
+// Task to generate API documentation
+tasks.register("generateApiDocs") {
+    group = "documentation"
+    description = "Generates API documentation from OpenAPI specification"
+
+    doFirst {
+        // Validate the OpenAPI specification before generating documentation
+        println("Validating OpenAPI specification...")
+        tasks.named("validateOpenApi").get().actions.forEach { action ->
+            action.execute(tasks.named("validateOpenApi").get())
+        }
+    }
+
+    doLast {
+        try {
+            // Ensure the output directory exists
+            mkdir("$projectDir/build/docs")
+
+            // Create version directory for documentation versioning
+            val docsVersionDir = file("$projectDir/src/jvmMain/resources/static/docs/v$projectVersion")
+            mkdir(docsVersionDir)
+
+            // Copy all generated documentation files to the static docs directory
+            copy {
+                from("$projectDir/build/generated-docs")
+                into("$projectDir/src/jvmMain/resources/static/docs")
+                include("**/*")
+            }
+
+            // Also copy to the versioned directory
+            copy {
+                from("$projectDir/build/generated-docs")
+                into(docsVersionDir)
+                include("**/*")
+            }
+
+            // Create a version.json file with version information
+            val timestamp = System.currentTimeMillis()
+            file("$projectDir/src/jvmMain/resources/static/docs/version.json").writeText("""
+                {
+                    "version": "$projectVersion",
+                    "generatedAt": "$timestamp",
+                    "latestVersionUrl": "/docs/v$projectVersion"
+                }
+            """.trimIndent())
+
+            println("API documentation generated successfully at:")
+            println("- Latest: $projectDir/src/jvmMain/resources/static/docs/")
+            println("- Versioned: $projectDir/src/jvmMain/resources/static/docs/v$projectVersion/")
+        } catch (e: Exception) {
+            println("Error generating API documentation: ${e.message}")
+            e.printStackTrace()
+            throw e
+        }
+    }
+
+    // This task depends on the openApiGenerate task
+    dependsOn("openApiGenerate")
 }

 kotlin {