Skip to content
Server Plugin

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 工件:

kotlin
implementation(ktorLibs.server.swagger)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.swagger
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-swagger-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

使用静态 OpenAPI 文件 ​

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

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

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

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

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

生成运行时 OpenAPI 元数据 ​

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

kotlin
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() 定义标签及其描述:

kotlin
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 属性:

kotlin
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 客户端标头。
kotlin
install(CORS) {
    anyHost()
    allowHeader(HttpHeaders.ContentType)
}