Ktor Server如何添加类似Spring doc-openapi-util的Swagger-UI？

核心依赖调整 #

替换原有依赖，引入Ktor官方的OpenAPI和Swagger支持组件，确保使用与你的Ktor版本匹配的稳定版：

// build.gradle.kts 示例配置
dependencies {
    implementation("io.ktor:ktor-server-openapi-jvm:$ktorVersion")
    implementation("io.ktor:ktor-server-swagger-jvm:$ktorVersion")
    // 必须：引入序列化组件，用于自动解析请求/响应结构
    implementation("io.ktor:ktor-server-content-negotiation-jvm:$ktorVersion")
    implementation("io.ktor:ktor-serialization-jackson-jvm:$ktorVersion")
}

封装全自动配置扩展 #

Ktor没有Spring式的零代码自动扫描，但可以通过封装扩展函数实现近似的全自动效果：

1. 创建Swagger自动配置扩展

import io.ktor.server.application.Application
import io.ktor.server.application.install
import io.ktor.server.openapi.OpenAPI
import io.ktor.server.openapi.configureOpenApi
import io.ktor.server.plugins.swagger.SwaggerUI
import io.ktor.server.routing.routing

fun Application.configureAutoSwagger() {
    // 自动初始化OpenAPI元数据，可根据项目需求修改
    install(OpenAPI) {
        info {
            title = "你的API服务名称"
            version = "v1.0"
            description = "自动生成的OpenAPI接口文档"
        }
    }

    // 自动注册Swagger UI访问路由，默认路径为/swagger
    install(SwaggerUI) {
        path = "/swagger"
        swaggerFile = "openapi/documentation.yaml"
    }

    // 自动扫描所有已注册路由并生成OpenAPI文档
    routing {
        configureOpenApi()
    }
}

2. 在主程序中启用配置
   在Ktor启动代码中直接调用扩展，无需手动逐个配置路由：

fun main() {
    embeddedServer(Netty, port = 8080) {
        configureContentNegotiation() // 确保先配置序列化组件
        configureAutoSwagger() // 启用全自动Swagger配置
        // 你的其他路由配置（分布在任意模块/扩展函数均可）
    }.start(wait = true)
}

增强注解支持（贴近Spring体验） #

通过Ktor的OpenAPI注解，可以像Spring那样标记接口、参数和响应结构：

import io.ktor.server.plugins.openapi.annotations.Parameter
import io.ktor.server.plugins.openapi.annotations.Response
import io.ktor.server.response.respond
import io.ktor.server.routing.get
import kotlinx.serialization.Serializable

@Serializable
data class UserResponse(val id: Int, val name: String)

routing {
    get("/users/{id}") {
        val userId = call.parameters["id"]?.toInt() ?: 0
        call.respond(UserResponse(userId, "测试用户"))
    }.apply {
        description = "根据ID获取用户详情"
        @Parameter(name = "id", description = "用户唯一ID", required = true)
        @Response(HttpStatusCode.OK, description = "成功返回用户信息", type = UserResponse::class)
    }
}

验证效果 #

启动服务后，访问http://localhost:8080/swagger即可看到自动生成的Swagger UI，所有已注册的路由会自动纳入文档，无需手动编写yaml/json配置。

注意：所有路由需在configureAutoSwagger()调用前完成注册，确保OpenAPI能扫描到完整的路由信息。

内容的提问来源于stack exchange，提问作者Евгений Поляк