如何将Kotlin原生文档解析后同步至swagger-ui？

• springdoc 1.6.6 内置的Javadoc解析逻辑依赖therapi扫描编译期生成的注释元数据，但Kotlin源码的KDoc默认不会走Java的annotationProcessor处理通道，你当前用annotationProcessor引入therapi的注解处理器，根本扫不到Kotlin文件里的注释，这是配置不生效的核心原因
• 你同时引入了WebMVC栈的springdoc-openapi-ui和WebFlux栈的springdoc-openapi-webflux-ui，两个依赖的自动配置存在优先级冲突，会干扰Javadoc解析组件的正常加载
• therapi 0.12.0本身没有默认开启Kotlin KDoc适配，需要显式传编译参数才能识别Kotlin注释

1. 修正依赖配置 #

首先调整构建脚本里的依赖，移除冲突包，把注解处理器从Java注解处理通道切换到Kotlin的kapt通道。以下是Gradle Kotlin DSL的正确配置示例，如果你用WebMVC而非WebFlux，把webflux对应的ui依赖替换成webmvc版本即可，两个ui依赖严禁同时引入：

plugins {
    // 确保已经引入kapt插件，没有的话先补上，版本和你项目用的Kotlin版本保持一致
    kotlin("kapt") version "1.6.21"
    // 其他原有插件...
}

val springdocVersion = "1.6.6"
val therapiVersion = "0.12.0"

dependencies {
    implementation("org.springdoc:springdoc-openapi-kotlin:$springdocVersion")
    // WebFlux项目留这行，WebMVC项目替换成implementation("org.springdoc:springdoc-openapi-ui:$springdocVersion")
    implementation("org.springdoc:springdoc-openapi-webflux-ui:$springdocVersion")
    implementation("org.springdoc:springdoc-openapi-javadoc:$springdocVersion")
    implementation("com.github.therapi:therapi-runtime-javadoc:$therapiVersion")
    // 重点：把annotationProcessor换成kapt引入注解处理器
    kapt("com.github.therapi:therapi-runtime-javadoc-scribe:$therapiVersion")
}

2. 配置kapt编译参数 #

给kapt添加therapi的Kotlin适配参数，让注解处理器能正确读取KDoc内容，在构建脚本里补充以下配置：

kapt {
    arguments {
        // 开启Kotlin KDoc解析支持
        arg("therapi.kotlin.enabled", "true")
        // 关闭私有成员扫描，减少无用元数据生成
        arg("therapi.includePrivate", "false")
    }
}

3. 添加应用配置 #

在项目的application.yml（或application.properties）里开启springdoc的Javadoc解析开关：

springdoc:
  javadoc:
    enabled: true

如果用properties配置，直接加springdoc.javadoc.enabled=true即可

4. 编译验证 #

执行./gradlew clean build全量编译项目，编译完成后查看build/generated/source/kapt目录，只要对应Controller、DTO类生成了XXXJavadoc后缀的生成类，就说明注释元数据采集正常。启动项目后swagger-ui会自动读取Kotlin源码里写的KDoc作为接口、字段的说明，不需要额外写@Operation、@Schema这类Swagger注解。

• 要生成文档的类、方法、字段不要用private修饰，therapi默认不会采集私有成员的注释
• 每次修改KDoc后如果发现文档没更新，先执行clean再重新编译，增量编译不会主动处理未变更类的注释
• therapi 0.12.0不支持Kotlin顶层函数的注释解析，接口路由方法必须写在Controller类内部，不要定义成顶层路由函数
• 如果项目用了Spring Security，记得把/v3/api-docs/**、/swagger-ui/**、/swagger-ui.html路径加入白名单，避免访问被拦截

内容的提问来源于stack exchange，提问作者sniff