Server Plugin

Swagger UI

所需依賴：io.ktor:ktor-server-swagger

程式碼範例： json-kotlinx-openapi

原生伺服器

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

支援: ✖️

Ktor 可讓您基於現有的 OpenAPI 規格，為您的專案產生並提供 Swagger UI。 透過 Swagger UI，您可以視覺化並與 API 資源互動。

提供以下工具，用於從程式碼產生 OpenAPI 定義，反之亦然：

• 適用於 IntelliJ IDEA 的 Ktor 外掛程式 提供了為伺服器端 Ktor 應用程式產生 OpenAPI 文件的能力。
• OpenAPI 產生器 允許您透過使用 kotlin-server 產生器，從您的 API 定義建立 Ktor 專案。或者，您可以使用 IntelliJ IDEA 的 功能。

新增依賴

提供 Swagger UI 服務需要在建置腳本中新增 ktor-server-swagger artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

設定 Swagger UI

若要提供 Swagger UI 服務，您需要呼叫 swaggerUI 方法，該方法會建立一個帶有 Swagger UI 的 GET 端點，位於從 swaggerFile 中的 OpenAPI 規格所呈現的 path：

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

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

此方法會嘗試在應用程式資源中尋找 OpenAPI 規格。 否則，它會嘗試使用 java.io.File 從檔案系統讀取 OpenAPI 規格。

您可以選擇在 swaggerUI 區塊內客製化 Swagger UI。 例如，您可以使用另一個 Swagger UI 版本或套用自訂樣式。

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

您現在可以 執行 應用程式並打開 /swagger 頁面，以查看可用的端點並進行測試。

設定 CORS

為了確保您的 API 能與 Swagger UI 良好運作，您需要為 跨來源資源共享 (CORS) 設定一個策略。 下方的範例套用了以下 CORS 設定：

• anyHost 啟用來自任何主機的跨來源請求；
• allowHeader 允許 內容協商 中使用的 Content-Type 用戶端標頭。

install(CORS) {
    anyHost()
    allowHeader(HttpHeaders.ContentType)
}