Server Plugin

Swagger UI

必要相依性：io.ktor:ktor-server-swagger

程式碼範例： json-kotlinx-openapi

原生伺服器

Ktor 支援 Kotlin/Native，可讓您在不使用額外執行時或虛擬機的情況下執行伺服器。

支援：✖️

Ktor 讓您能根據 OpenAPI 規格為專案產生並提供 Swagger UI。 透過 Swagger UI，您可以直接從瀏覽器中將您的 API 端點可視化並進行互動。

您可以透過以下任一方式提供 OpenAPI 規格：

• 提供現有的 YAML 或 JSON 檔案。
• 使用 OpenAPI 編譯器擴充套件與執行時 API 在執行時產生規格。

新增相依性

提供 Swagger UI 需要在組建指令碼中新增 ktor-server-swagger 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

在 Ktor 3.4.0 中，SwaggerUI 外掛程式需要 ktor-server-routing-openapi 相依性。 這並非刻意的破壞性變更，並將在 Ktor 3.4.1 中修正。 如果您使用的是 Ktor 3.4.0，請手動新增該相依性以避免執行時錯誤。

使用靜態 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 {} 區塊內自訂 Swagger UI，例如指定自訂的 Swagger UI 版本：

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

配置 CORS

為了確保 Swagger UI 能夠正確存取您的 API 端點，您需要先配置跨來源資源共用 (CORS)。

下方的範例套用了以下 CORS 配置：

• anyHost 啟用來自任何主機的跨來源要求。
• allowHeader 允許用於內容交涉的 Content-Type 用戶端標頭。

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