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)
}