Server Plugin

OpenAPI

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

程式碼範例： json-kotlinx-openapi

原生伺服器

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

支援：✖️

Ktor 允許您根據 OpenAPI 規格提供 OpenAPI 文件。

您可以使用以下其中一種方式提供 OpenAPI 規格：

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

在上述兩種情況下，OpenAPI 外掛程式都會在伺服器上組合規格，並將文件算繪為 HTML。

加入相依性

• 提供 OpenAPI 文件需要在建置指令碼中加入 ktor-server-openapi 構件：

  Gradle (Kotlin)Gradle (Groovy)Maven

• （選填）如果您想要自訂 程式碼產生器，請加入 swagger-codegen-generators 相依性：

  Gradle (Kotlin)Gradle (Groovy)Maven

  您可以將 $swagger_codegen_version 替換為所需的 swagger-codegen-generators 構件版本，例如 1.0.36。

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

使用靜態 OpenAPI 檔案

若要從現有規格提供 OpenAPI 文件，請使用 openAPI() 函式並提供 OpenAPI 文件的路徑。

以下範例在 openapi 路徑建立了一個 GET 端點，並從提供的 OpenAPI 規格檔案算繪 Swagger UI：

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

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

外掛程式會首先在應用程式資源中尋找規格。若未找到，則會嘗試使用 java.io.File 從檔案系統載入。

產生執行時 OpenAPI 元資料

您可以改為使用 OpenAPI 編譯器外掛程式與路由註解產生的元資料在執行時產生 OpenAPI 規格，而不必依賴靜態檔案。

在此模式下，OpenAPI 外掛程式會直接從路由樹組合規格：

 openAPI(path = "openapi") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing {
        routingRoot.descendants()
    }
}

如此一來，您便可以在 /openapi 路徑存取產生的 OpenAPI 文件，該文件反映了應用程式的當前狀態。

如需更多關於 OpenAPI 編譯器擴充套件與執行時 API 的資訊，請參閱 OpenAPI 規格產生。

設定 OpenAPI

預設情況下，文件會使用 StaticHtml2Codegen 進行算繪。您可以在 openAPI {} 區塊中自訂算繪器：

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