Server Plugin

Swagger UI

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

コード例: json-kotlinx-openapi

Native サーバー

Ktor は Kotlin/Native をサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。

のサポート: ✖️

Ktor は、既存の OpenAPI 仕様に基づいて、プロジェクト用の Swagger UI を生成して提供できます。 Swagger UI を使用すると、API リソースを視覚化し、操作できます。既存の YAML または JSON 仕様を提供したり、Ktor Gradle プラグインの OpenAPI 拡張機能を使用して生成したりできます。

依存関係を追加する

Swagger UI を提供するには、ビルドスクリプトに ktor-server-swagger アーティファクトを追加する必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

Swagger UI を設定する

Swagger UI を提供するには、swaggerFile に配置された OpenAPI 仕様からレンダリングされる、path に Swagger UI を含む GET エンドポイントを作成する swaggerUI メソッドを呼び出す必要があります。

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

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

このメソッドは、アプリケーションリソース内で OpenAPI 仕様を検索しようとします。 それ以外の場合は、java.io.File を使用してファイルシステムから OpenAPI 仕様を読み込もうとします。

オプションで、swaggerUI ブロック内で Swagger UI をカスタマイズできます。 たとえば、別の Swagger UI バージョンを使用したり、カスタムスタイルを適用したりできます。

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

これでアプリケーションを実行し、/swagger ページを開いて利用可能なエンドポイントを確認し、テストできます。

CORS を設定する

API が Swagger UI とうまく連携するようにするには、Cross-Origin Resource Sharing (CORS) のポリシーを設定する必要があります。 以下の例は、次の CORS 設定を適用します。

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

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