Skip to content
Server Plugin

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 構件:

kotlin
implementation(ktorLibs.server.swagger)
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.swagger
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-swagger-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

使用靜態 OpenAPI 檔案 ​

若要從現有的 OpenAPI 規格檔案提供 Swagger UI,請使用 swaggerUI() 函式並指定檔案位置。

以下範例在 swagger 路徑建立一個 GET 端點,並從提供的 OpenAPI 規格檔案轉譯 Swagger UI:

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

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

該外掛程式會先在應用程式資源中尋找該規格。如果找不到,它會嘗試使用 java.io.File 從檔案系統載入。

產生執行時期 OpenAPI 元資料 ​

除了依賴靜態檔案之外,您也可以使用 OpenAPI 編譯器外掛程式與路由註解所產生的元資料,在執行時期產生 OpenAPI 規格:

kotlin
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() 來定義標籤及其說明:

kotlin
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 屬性:

kotlin
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 用戶端標頭。
kotlin
install(CORS) {
    anyHost()
    allowHeader(HttpHeaders.ContentType)
}