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,請使用 swaggerUI() 函式搭配 Swagger UI 5.x。如果你需要繼續使用 OpenAPI 外掛程式的 HTML 呈現器,請將規格保持在 OpenAPI 3.0.3。
