如何在Ktor中生成openapi.yml？官方插件报错求助

问题分析 #

你使用ktor-server-openapi插件后出现FileNotFoundException，是因为这个插件的作用是暴露你手动编写好的OpenAPI文档文件，而非自动生成文档。它会尝试读取你指定的documentation.yaml文件（默认从资源目录加载），如果文件不存在就会报错。而你的需求是自动生成OpenAPI规范文件，因此需要使用Ktor官方提供的自动生成插件。

正确解决方案 #

使用ktor-server-openapi-generator插件，它可以根据你的路由定义、数据类元信息自动生成符合OpenAPI规范的文档，支持直接导出为YAML文件，无需依赖Swagger界面。

步骤1：添加依赖 #

在你的构建文件（如build.gradle.kts）中添加以下依赖（替换$ktor_version为你使用的Ktor版本，要求2.0+）：

implementation("io.ktor:ktor-server-openapi-generator:$ktor_version")
implementation("io.ktor:ktor-server-content-negotiation:$ktor_version")
// 根据你使用的序列化库选择，这里以Jackson为例
implementation("io.ktor:ktor-serialization-jackson:$ktor_version")

步骤2：配置应用模块 #

修改你的应用模块代码，安装必要的插件并配置自动生成逻辑：

import io.ktor.server.application.*
import io.ktor.server.plugins.openapigenerator.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
import io.ktor.server.routing.*
import io.ktor.server.response.*
import java.io.File

fun main() {
    embeddedServer(
        Netty,
        port = Config.load().main.port,
        host = Config.load().main.host,
        module = Application::module
    ).start(wait = true)
}

fun Application.module() {
    // 安装内容协商插件，用于序列化数据类生成OpenAPI Schema
    install(ContentNegotiation) {
        jackson()
    }

    // 安装OpenAPI生成器插件，配置文档基础信息
    install(OpenAPIGenerator) {
        info {
            title = "TinyCloudAPI"
            version = "1.0.0"
            description = "自动生成的REST API OpenAPI文档"
        }
        servers {
            server("http://${Config.load().main.host}:${Config.load().main.port}") {
                description = "当前运行环境"
            }
        }
    }

    routing {
        route("/api") {
            // 给路由添加元数据，用于生成文档标签、描述
            get(tags = setOf("基础接口"), description = "返回Hello World") {
                call.respond("Hello world!")
            }

            // 如果有数据类作为响应体，插件会自动生成对应的Schema
            get("/user/{id}", tags = setOf("用户接口"), description = "根据ID获取用户信息") {
                val userId = call.parameters["id"] ?: ""
                call.respond(User(userId, "示例用户"))
            }
        }

        // 可选：暴露HTTP端点用于获取OpenAPI文档（JSON格式）
        openAPI(path = "/api/openapi")

        // 核心：自动生成并导出OpenAPI YAML文件到项目根目录
        val openApiSpec = openAPIGenerator.generateOpenAPI()
        File("openapi.yml").writeText(openApiSpec.toYaml())
    }
}

// 示例数据类，会自动生成对应的OpenAPI Schema
data class User(val id: String, val name: String)

效果说明 #

• 启动应用后，会在项目根目录自动生成openapi.yml文件，包含所有路由的文档信息、数据类Schema。
• 若需要通过HTTP访问文档，可以访问http://<host>:<port>/api/openapi获取JSON格式的规范，也可以自行转换为YAML。

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