Server Plugin

Swagger UI

必需的依赖项：io.ktor:ktor-server-swagger

代码示例： json-kotlinx-openapi

原生服务器

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

支持：✖️

Ktor 允许您基于 OpenAPI 规范为项目生成并提供 Swagger UI。 借助 Swagger UI，您可以直接在浏览器中可视化您的 API 端点并与其交互。

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

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

添加依赖项

提供 Swagger UI 需要在构建脚本中添加 ktor-server-swagger 构件：

Gradle (Kotlin)Gradle (Groovy)Maven

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

使用静态 OpenAPI 文件

要从现有的 OpenAPI 规范文件提供 Swagger UI，请使用 swaggerUI() 函数并指定文件位置。

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

import io.ktor.server.plugins.swagger.*

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

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

在运行时生成 OpenAPI 元数据

除了依赖静态文件外，您还可以使用 OpenAPI 编译器插件生成的元数据和路由注解在运行时生成 OpenAPI 规范：

swaggerUI("/swaggerUI") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing(ContentType.Application.Json) {
        routingRoot.descendants()
    }
}

借助此功能，您可以在 /swaggerUI 路径处访问生成的 OpenAPI 文档，该文档反映了应用程序的当前状态。

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

配置 Swagger UI

您可以在 swaggerUI {} 代码块中自定义 Swagger UI，例如通过指定自定义的 Swagger UI 版本：

routing {
    swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml") {
        version = "4.15.5"
    }
}

配置 CORS

为了确保 Swagger UI 能够正确访问您的 API 端点，您需要先配置跨源资源共享 (CORS)。

下面的示例应用了以下 CORS 配置：

• anyHost 允许来自任何主机的跨源请求。
• allowHeader 允许用于内容协商的 Content-Type 客户端标头。

install(CORS) {
    anyHost()
    allowHeader(HttpHeaders.ContentType)
}