Server Plugin

Swagger UI

所需依赖项: io.ktor:ktor-server-swagger

代码示例: json-kotlinx-openapi

原生服务器

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

支持: ✖️

Ktor 允许您基于现有 OpenAPI 规范为您的项目生成并提供 Swagger UI。借助 Swagger UI，您可以可视化 API 资源并与之交互。您可以提供现有的 YAML 或 JSON 规范，也可以使用 Ktor Gradle 插件的 OpenAPI 扩展 生成一个。

添加依赖项

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

Gradle (Kotlin)Gradle (Groovy)Maven

配置 Swagger UI

要提供 Swagger UI，您需要调用 swaggerUI 方法，该方法会在 path 上创建一个 GET 端点，其 Swagger UI 是从位于 swaggerFile 的 OpenAPI 规范渲染而来的：

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

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

此方法尝试在应用程序资源中查找 OpenAPI 规范。否则，它会尝试使用 java.io.File 从文件系统读取 OpenAPI 规范。

（可选）您可以在 swaggerUI 代码块内部定制 Swagger UI。例如，您可以使用另一个 Swagger UI 版本或应用自定义样式。

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

现在，您可以运行应用程序并打开 /swagger 页面，以查看可用的端点并测试它们。

配置 CORS

为了确保您的 API 与 Swagger UI 良好协作，您需要为跨域资源共享 (CORS) 设置策略。以下示例应用了以下 CORS 配置：

• anyHost 启用来自任何主机的跨域请求；
• allowHeader 允许在内容协商中使用的 Content-Type 客户端标头。

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