Server Plugin

OpenAPI

所需依赖项：io.ktor:ktor-server-openapi

代码示例： json-kotlinx-openapi

原生服务器

Ktor 支持 Kotlin/Native，允许您在没有额外运行时或虚拟机的情况下运行服务器。

支持：✖️

Ktor 允许您基于 OpenAPI 规范提供 OpenAPI 文档。

您可以通过以下方式之一提供 OpenAPI 规范：

• 提供现有的 YAML 或 JSON 文件。
• 使用 OpenAPI 编译器扩展和运行时 API 在运行时生成规范。

在这两种情况下，OpenAPI 插件都会在服务器上组装规范，并将文档渲染为 HTML。

添加依赖项

• 提供 OpenAPI 文档需要在构建脚本中添加 ktor-server-openapi 构件：

  Gradle (Kotlin)Gradle (Groovy)Maven

• （可选）如果您想自定义代码生成器，请添加 swagger-codegen-generators 依赖项：

  Gradle (Kotlin)Gradle (Groovy)Maven

  您可以将 $swagger_codegen_version 替换为所需的 swagger-codegen-generators 构件版本，例如 1.0.36。

在 Ktor 3.4.0 中，OpenAPI 插件需要 ktor-server-routing-openapi 依赖项。 这并非有意的破坏性改动，并将在 Ktor 3.4.1 中得到修正。 如果您使用的是 Ktor 3.4.0，请手动添加该依赖项以避免运行时错误。

使用静态 OpenAPI 文件

要从现有规范提供 OpenAPI 文档，请使用 openAPI() 函数并提供 OpenAPI 文档的路径。

以下示例在 openapi 路径处创建了一个 GET 端点，并根据提供的 OpenAPI 规范文件渲染 Swagger UI：

import io.ktor.server.plugins.openapi.*

// ...
routing {
    openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml")
}

该插件首先在应用程序资源中查找规范。如果未找到，它将尝试使用 java.io.File 从文件系统中加载它。

生成运行时 OpenAPI 元数据

您可以不依赖静态文件，而是使用由 OpenAPI 编译器插件和路由注解生成的元数据，在运行时生成 OpenAPI 规范。

在此模式下，OpenAPI 插件直接从路由树组装规范：

 openAPI(path = "openapi") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing {
        routingRoot.descendants()
    }
}

这样一来，您就可以在 /openapi 路径访问生成的 OpenAPI 文档，该文档反映了应用程序的当前状态。

有关 OpenAPI 编译器扩展和运行时 API 的更多信息，请参阅 OpenAPI 规范生成。

配置 OpenAPI

默认情况下，文档使用 StaticHtml2Codegen 渲染。您可以在 openAPI {} 代码块中自定义渲染器：

routing {
    openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml") {
        codegen = StaticHtmlCodegen()
    }
}