Swagger UI
所需依赖项:io.ktor:ktor-server-swagger
代码示例: json-kotlinx-openapi
Native 服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✖️
Ktor 允许您根据 OpenAPI 规范为项目生成并提供 Swagger UI。 借助 Swagger UI,您可以直接在浏览器中可视化 API 端点并与之交互。
您可以通过以下任一方式提供 OpenAPI 规范:
添加依赖项
提供 Swagger UI 需要在构建脚本中添加 ktor-server-swagger 工件:
使用静态 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 {} 配置块,您可以配置 OpenAPI 文档并自定义 Swagger UI。
配置文档元数据
您可以直接在配置块中定义顶级 OpenAPI 元数据。
例如,使用 info 指定常规 API 信息,并使用 tag() 定义标签及其描述:
swaggerUI("/swagger") {
info = OpenApiInfo("Books API from routes", "1.0.0")
tag(
name = "Books",
description = "Operations on books"
)
}您还可以配置其他顶级 OpenAPI 属性,例如服务器、安全要求、可重用组件、外部文档和规范扩展。
有关可用选项的完整集合,请参阅 SwaggerConfig API 参考。
配置 Swagger UI 版本
默认情况下,Ktor 使用预定义的 Swagger UI 版本。要使用其他版本,请设置 version 属性:
routing {
swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml") {
version = "5.31.0"
}
}OpenAPI 3.1.x 文档需要 Swagger UI 5.x,而 Swagger UI 4.x 仅支持 OpenAPI 3.0.x。
配置 CORS
为了确保 Swagger UI 能够正确访问您的 API 端点,您需要首先配置跨源资源共享 (CORS)。
以下示例应用了以下 CORS 配置:
anyHost允许来自任意主机的跨源请求。allowHeader允许用于内容协商的Content-Type客户端标头。
install(CORS) {
anyHost()
allowHeader(HttpHeaders.ContentType)
}