OpenAPI
所需依赖项:io.ktor:ktor-server-openapi
代码示例: json-kotlinx-openapi
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✖️
Ktor 允许你基于 OpenAPI 规范提供 OpenAPI 文档服务。
你可以通过以下方式之一提供 OpenAPI 规范:
在这两种情况下,OpenAPI 插件都会在服务器上装配规范,并将文档渲染为 HTML。
添加依赖项
提供 OpenAPI 文档服务需要在构建脚本中添加
ktor-server-openapi构件:(可选)如果你想自定义代码生成器,请添加
swagger-codegen-generators依赖项:kotlinimplementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")groovyimplementation "io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version"xml<dependency> <groupId>io.swagger.codegen.v3</groupId> <artifactId>swagger-codegen-generators</artifactId> <version>${swagger_codegen_version}</version> </dependency>你可以将
$swagger_codegen_version替换为所需版本的swagger-codegen-generators构件,例如1.0.47。
使用静态 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
openAPI {} 配置块允许你配置生成的 OpenAPI 文档以及 Ktor 渲染文档的方式。
配置文档元数据
你可以直接在配置块中定义顶层 OpenAPI 元数据。
例如,使用 info 指定常规 API 信息,使用 tag() 定义标签及其描述:
openAPI("openapi") {
info = OpenApiInfo("Books API from routes", "1.0.0")
tag(
name = "Books",
description = "Operations on books"
)
}你还可以配置其他顶层 OpenAPI 属性,例如服务器、安全要求、可重用组件、外部文档和规范扩展。
有关可用选项的完整列表,请参阅 OpenAPIConfig API 参考。
配置文档渲染器
默认情况下,文档使用 StaticHtml2Codegen 进行渲染。
若要使用不同的渲染器,请将其赋值给 codegen 属性:
routing {
openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml") {
codegen = StaticHtmlCodegen()
}
}StaticHtmlCodegen 和 StaticHtml2Codegen 仅支持 OpenAPI 3.0.x 文档。将它们用于 OpenAPI 3.1 文档可能会生成不完整或不正确的 HTML。对于 OpenAPI 3.1,请使用搭配 Swagger UI 5.x 的 swaggerUI() 函数。如果需要继续使用 OpenAPI 插件的 HTML 渲染器,请将规范保持在 OpenAPI 3.0.3。
