Publish KDoc for the Kotlin DSL

Applies Dokka to any subproject using security-kotlin via DocsPlugin,
aggregates KDoc alongside Javadoc in syncAntoraAttachments, and adds
a Kotlin API entry to the reference docs navigation.

Closes gh-18968

Signed-off-by: Josh Cummings <3627351+jzheaux@users.noreply.github.com>

Author: jzheaux

buildSrc/build.gradle

@@ -3,6 +3,7 @@ plugins {
 	id "groovy-gradle-plugin"
 	id "java"
 	id "groovy"
+	id "org.jetbrains.dokka" version "2.1.0"
 }
 
 java {
@@ -79,6 +80,7 @@ dependencies {
 	implementation libs.io.spring.javaformat.spring.javaformat.gradle.plugin
 	implementation libs.io.spring.nohttp.nohttp.gradle
 	implementation libs.org.jetbrains.kotlin.kotlin.gradle.plugin
+	implementation libs.org.jetbrains.dokka.dokka.gradle.plugin
 	implementation (libs.net.sourceforge.htmlunit) {
 		exclude group: 'org.eclipse.jetty.websocket', module: 'websocket-client'
 	}

buildSrc/src/main/groovy/io/spring/gradle/convention/DocsPlugin.groovy

@@ -19,12 +19,32 @@ public class DocsPlugin implements Plugin<Project> {
 		PluginManager pluginManager = project.getPluginManager();
 		pluginManager.apply(BasePlugin);
 		pluginManager.apply(JavadocApiPlugin);
+		pluginManager.apply("org.jetbrains.dokka");
+
+		project.rootProject.subprojects { subproject ->
+			subproject.pluginManager.withPlugin("security-kotlin") {
+				subproject.pluginManager.apply("org.jetbrains.dokka")
+				configureDokka(subproject)
+				project.dependencies.add("dokka", subproject)
+			}
+		}
+
+		project.extensions.configure("dokka") { dokka ->
+			dokka.moduleName.set(Utils.getProjectName(project) + " Kotlin API")
+		}
+
+		project.tasks.named("dokkaGeneratePublicationHtml").configure { it.dependsOn("api") }
 
 		project.tasks.register("syncAntoraAttachments", Sync) { sync ->
 			sync.group = 'Documentation'
 			sync.description = 'Syncs the Antora attachments'
-			sync.from(project.provider({ project.tasks.api.outputs }))
-			sync.into(project.layout.buildDirectory.dir('generated-antora-resources/modules/ROOT/assets/attachments/api/java'))
+			sync.into(project.layout.buildDirectory.dir('generated-antora-resources/modules/ROOT/assets/attachments/api'))
+			sync.from(project.provider({ project.tasks.api.outputs })) { copy ->
+				copy.into('java')
+			}
+			sync.from(project.tasks.named("dokkaGeneratePublicationHtml")) { copy ->
+				copy.into('kotlin')
+			}
 		}
 
 		project.tasks.register("generateAntoraResources") {
@@ -53,4 +73,16 @@ public class DocsPlugin implements Plugin<Project> {
 		}
 		project.tasks.assemble.dependsOn docs
 	}
+
+	void configureDokka(Project project) {
+		project.extensions.configure("dokka") { dokka ->
+			dokka.dokkaSourceSets.configureEach { spec ->
+				spec.suppressedFiles.from(project.fileTree("src/main/java"))
+				spec.externalDocumentationLinks.register("javadoc") {
+					it.url.set(new URI("https://docs.spring.io/${Utils.getProjectName(project)}/reference/${project.rootProject.version}/api/java/"))
+					it.packageListUrl.set(project.layout.buildDirectory.file("api/element-list").get().asFile.toURI())
+				}
+			}
+		}
+	}
 }

docs/modules/ROOT/nav.adoc

@@ -11,6 +11,7 @@
 ** xref:migration/reactive.adoc[Reactive]
 * xref:getting-spring-security.adoc[Getting Spring Security]
 * xref:attachment$api/java/index.html[Javadoc]
+* xref:attachment$api/kotlin/index.html[KDoc]
 * xref:features/index.adoc[Features]
 ** xref:features/authentication/index.adoc[Authentication]
 *** xref:features/authentication/password-storage.adoc[Password Storage]

gradle/libs.versions.toml

@@ -8,6 +8,7 @@ org-apache-maven-resolver = "1.9.27"
 org-aspectj = "1.9.25.1"
 org-bouncycastle = "1.83"
 org-eclipse-jetty = "11.0.26"
+org-jetbrains-dokka = "2.1.0"
 org-jetbrains-kotlin = "2.3.20"
 org-jetbrains-kotlinx = "1.10.2"
 org-mockito = "5.23.0"
@@ -67,6 +68,7 @@ org-eclipse-jetty-jetty-servlet = { module = "org.eclipse.jetty:jetty-servlet",
 org-hamcrest = "org.hamcrest:hamcrest:2.2"
 org-hibernate-orm-hibernate-core = "org.hibernate.orm:hibernate-core:7.3.0.Final"
 org-hsqldb = "org.hsqldb:hsqldb:2.7.4"
+org-jetbrains-dokka-dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "org-jetbrains-dokka" }
 org-jetbrains-kotlin-kotlin-bom = { module = "org.jetbrains.kotlin:kotlin-bom", version.ref = "org-jetbrains-kotlin" }
 org-jetbrains-kotlin-kotlin-gradle-plugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "org-jetbrains-kotlin" }
 org-jetbrains-kotlinx-kotlinx-coroutines-bom = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-bom", version.ref = "org-jetbrains-kotlinx" }