Dokumentations-Tasks

docs/api/generated/events-openapi.json

@@ -2,35 +2,19 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Events API",
-    "description": "REST API for events management",
+    "description": "REST API für events Verwaltung",
     "version": "1.0.0",
-    "contact": {
-      "name": "Meldestelle Development Team"
-    }
+    "contact": { "name": "Meldestelle Development Team" }
   },
   "servers": [
-    {
-      "url": "http://localhost:8080",
-      "description": "Development server"
-    },
-    {
-      "url": "https://api.meldestelle.at",
-      "description": "Production server"
-    }
+    { "url": "http://localhost:8080", "description": "Entwicklungs-Server" },
+    { "url": "https://api.meldestelle.at", "description": "Produktions-Server" }
   ],
   "paths": {},
   "components": {
     "securitySchemes": {
-      "bearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
     }
   },
-  "security": [
-    {
-      "bearerAuth": []
-    }
-  ]
+  "security": [ { "bearerAuth": [] } ]
 }

docs/api/generated/horses-openapi.json

@@ -2,35 +2,19 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Horses API",
-    "description": "REST API for horses management",
+    "description": "REST API für horses Verwaltung",
     "version": "1.0.0",
-    "contact": {
-      "name": "Meldestelle Development Team"
-    }
+    "contact": { "name": "Meldestelle Development Team" }
   },
   "servers": [
-    {
-      "url": "http://localhost:8080",
-      "description": "Development server"
-    },
-    {
-      "url": "https://api.meldestelle.at",
-      "description": "Production server"
-    }
+    { "url": "http://localhost:8080", "description": "Entwicklungs-Server" },
+    { "url": "https://api.meldestelle.at", "description": "Produktions-Server" }
   ],
   "paths": {},
   "components": {
     "securitySchemes": {
-      "bearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
     }
   },
-  "security": [
-    {
-      "bearerAuth": []
-    }
-  ]
+  "security": [ { "bearerAuth": [] } ]
 }

docs/api/generated/masterdata-openapi.json

@@ -2,35 +2,19 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Masterdata API",
-    "description": "REST API for masterdata management",
+    "description": "REST API für masterdata Verwaltung",
     "version": "1.0.0",
-    "contact": {
-      "name": "Meldestelle Development Team"
-    }
+    "contact": { "name": "Meldestelle Development Team" }
   },
   "servers": [
-    {
-      "url": "http://localhost:8080",
-      "description": "Development server"
-    },
-    {
-      "url": "https://api.meldestelle.at",
-      "description": "Production server"
-    }
+    { "url": "http://localhost:8080", "description": "Entwicklungs-Server" },
+    { "url": "https://api.meldestelle.at", "description": "Produktions-Server" }
   ],
   "paths": {},
   "components": {
     "securitySchemes": {
-      "bearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
     }
   },
-  "security": [
-    {
-      "bearerAuth": []
-    }
-  ]
+  "security": [ { "bearerAuth": [] } ]
 }

docs/api/generated/members-openapi.json

@@ -2,35 +2,19 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Members API",
-    "description": "REST API for members management",
+    "description": "REST API für members Verwaltung",
     "version": "1.0.0",
-    "contact": {
-      "name": "Meldestelle Development Team"
-    }
+    "contact": { "name": "Meldestelle Development Team" }
   },
   "servers": [
-    {
-      "url": "http://localhost:8080",
-      "description": "Development server"
-    },
-    {
-      "url": "https://api.meldestelle.at",
-      "description": "Production server"
-    }
+    { "url": "http://localhost:8080", "description": "Entwicklungs-Server" },
+    { "url": "https://api.meldestelle.at", "description": "Produktions-Server" }
   ],
   "paths": {},
   "components": {
     "securitySchemes": {
-      "bearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
     }
   },
-  "security": [
-    {
-      "bearerAuth": []
-    }
-  ]
+  "security": [ { "bearerAuth": [] } ]
 }

docs/build.gradle.kts

@@ -0,0 +1,139 @@
+import org.gradle.api.tasks.*
+import org.gradle.kotlin.dsl.*
+import java.util.Locale
+import javax.inject.Inject
+
+plugins {
+    // no special plugins required for these custom tasks
+}
+
+abstract class ValidateDocumentationTask @Inject constructor(
+    private val execOperations: ExecOperations
+) : DefaultTask() {
+
+    @get:InputFile
+    abstract val scriptFile: RegularFileProperty
+
+    @get:InputFiles
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    abstract val docsSources: ConfigurableFileCollection
+
+    // When true, a non-zero exit from the validation script will fail the task
+    @get:Input
+    abstract val strict: Property<Boolean>
+
+    @TaskAction
+    fun validate() {
+        logger.lifecycle("Validating documentation…")
+        val result = execOperations.exec {
+            workingDir(project.rootDir)
+            // Do not throw automatically on non-zero exit; we'll handle it manually
+            isIgnoreExitValue = true
+            val script = scriptFile.get().asFile
+            val os = System.getProperty("os.name").lowercase(Locale.getDefault())
+            if (os.contains("win")) {
+                commandLine("bash", script.absolutePath)
+            } else {
+                commandLine(script.absolutePath)
+            }
+        }
+        val code = result.exitValue
+        if (code != 0) {
+            val message = "Documentation validation script exited with code $code"
+            if (strict.getOrElse(false)) {
+                throw GradleException(message)
+            } else {
+                logger.warn("$message — continuing because strict mode is disabled. Use -PdocsValidateStrict=true to enforce failures.")
+            }
+        }
+    }
+}
+
+@CacheableTask
+abstract class GenerateOpenApiDocsTask : DefaultTask() {
+    @get:Input
+    abstract val apiModules: ListProperty<String>
+
+    @get:Input
+    abstract val apiVersion: Property<String>
+
+    @get:OutputDirectory
+    abstract val outputDir: DirectoryProperty
+
+    @TaskAction
+    fun generate() {
+        val out = outputDir.get().asFile.apply { mkdirs() }
+        apiModules.get().forEach { module ->
+            val moduleName = module.substringAfterLast(":").removeSuffix("-api")
+            val specFile = out.resolve("${moduleName}-openapi.json")
+            specFile.writeText(
+                """
+                {
+                  "openapi": "3.0.3",
+                  "info": {
+                    "title": "${moduleName.replaceFirstChar { if (it.isLowerCase()) it.titlecase(Locale.getDefault()) else it.toString() }} API",
+                    "description": "REST API für $moduleName Verwaltung",
+                    "version": "${apiVersion.get()}",
+                    "contact": { "name": "Meldestelle Development Team" }
+                  },
+                  "servers": [
+                    { "url": "http://localhost:8080", "description": "Entwicklungs-Server" },
+                    { "url": "https://api.meldestelle.at", "description": "Produktions-Server" }
+                  ],
+                  "paths": {},
+                  "components": {
+                    "securitySchemes": {
+                      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
+                    }
+                  },
+                  "security": [ { "bearerAuth": [] } ]
+                }
+                """.trimIndent()
+            )
+            logger.lifecycle("Generated ${specFile.relativeTo(project.rootDir)}")
+        }
+    }
+}
+
+val generatedDir = layout.projectDirectory.dir("api/generated")
+
+tasks.register<GenerateOpenApiDocsTask>("generateOpenApiDocs") {
+    group = "documentation"
+    description = "Generates OpenAPI docs for all API modules"
+    apiModules.set(listOf(
+        "members:members-api",
+        "horses:horses-api",
+        "events:events-api",
+        "masterdata:masterdata-api"
+    ))
+    apiVersion.set("1.0.0")
+    // since this project directory is the repo's docs/, write to docs/api/generated
+    outputDir.set(generatedDir)
+}
+
+tasks.register<ValidateDocumentationTask>("validateDocumentation") {
+    group = "documentation"
+    description = "Validates documentation completeness and consistency (use -PdocsValidateStrict=true to fail on issues)"
+    // Ensure generated OpenAPI docs are available before validation
+    dependsOn(tasks.named("generateOpenApiDocs"))
+    // script lives in root/scripts/validation
+    scriptFile.set(layout.projectDirectory.file("../scripts/validation/validate-docs.sh"))
+    // treat all markdown, yaml and generated json files within docs/ as inputs
+    docsSources.from(
+        layout.projectDirectory.asFileTree.matching { include("**/*.md") },
+        layout.projectDirectory.asFileTree.matching { include("**/*.yml", "**/*.yaml") },
+        layout.projectDirectory.dir("api/generated").asFileTree.matching { include("**/*.json") }
+    )
+    // strict mode from Gradle property (default: false)
+    strict.set(
+        providers.gradleProperty("docsValidateStrict")
+            .map { it.equals("true", ignoreCase = true) }
+            .orElse(false)
+    )
+}
+
+tasks.register("generateAllDocs") {
+    group = "documentation"
+    description = "Generates all documentation (API + validation)"
+    dependsOn("generateOpenApiDocs", "validateDocumentation")
+}