Skip to content
Server Plugin

OpenAPI

必要的相依性:io.ktor:ktor-server-openapi

程式碼範例: json-kotlinx-openapi

原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。支援:✖️

Ktor 允許你根據 OpenAPI 規格提供 OpenAPI 文件服務。

你可以透過以下其中一種方式提供 OpenAPI 規格:

在這兩種情況下,OpenAPI 外掛程式都會在伺服器端組裝規格並將文件呈現為 HTML。

新增相依性 ​

  • 提供 OpenAPI 文件服務需要在建置指令碼中新增 ktor-server-openapi 構件:

    kotlin
    implementation(ktorLibs.server.openapi)
    上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
    groovy
    implementation ktorLibs.server.openapi
    上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-openapi-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  • (選用)如果你想要自訂程式碼產生器,請新增 swagger-codegen-generators 相依性:

    kotlin
    implementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")
    groovy
    implementation "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:

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

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

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

於執行階段產生 OpenAPI 元資料 ​

除了依賴靜態檔案之外,你還可以利用 OpenAPI 編譯器外掛程式所產生的元資料以及路由註解,在執行階段產生 OpenAPI 規格。

在此模式下,OpenAPI 外掛程式會直接從路由樹組裝規格:

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

kotlin
openAPI("openapi") {
    info = OpenApiInfo("Books API from routes", "1.0.0")
    tag(
        name = "Books",
        description = "Operations on books"
    )
}

你也可以設定其他頂層 OpenAPI 屬性,例如伺服器、安全需求、可重複使用的組件、外部文件和規格擴充套件。

如需所有可用選項的完整清單,請參閱 OpenAPIConfig API 參考。

設定文件呈現器 ​

預設情況下,文件會使用 StaticHtml2Codegen 呈現。

若要使用不同的呈現器,請將其指派給 codegen 屬性:

kotlin
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。