Server Plugin

Swagger UI

必要な依存関係: io.ktor:ktor-server-swagger

コード例: json-kotlinx-openapi

Native サーバー

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 仕様は、次のいずれかの方法で提供できます。

• 既存の 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()
    }
}

これにより、アプリケーションの現在の状態を反映した、生成された OpenAPI ドキュメントに /swaggerUI パスでアクセスできます。

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 エンドポイントに正しくアクセスできるようにするには、まず Cross-Origin Resource Sharing (CORS) を設定する必要があります。

以下の例では、次の CORS 設定を適用しています。

• anyHost は、任意のホストからのクロスオリジンリクエストを有効にします。
• allowHeader は、コンテンツネゴシエーションに使用される Content-Type クライアントヘッダーを許可します。

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