Server Plugin

Swagger UI

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

コード例: json-kotlinx-openapi

Native サーバー

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

のサポート: ✖️

Ktor は、既存の OpenAPI 仕様に基づいて、プロジェクト用の Swagger UI を生成して提供できます。Swagger UI を使用すると、API リソースを視覚化し、操作できます。

コードから OpenAPI 定義を生成したり、その逆を行ったりするために、次のツールを利用できます。

• IntelliJ IDEA 用の Ktor プラグイン は、サーバーサイド Ktor アプリケーションの OpenAPI ドキュメントを生成する機能を提供します。
• OpenAPI generator を使用すると、kotlin-server ジェネレーターを使って、API 定義から Ktor プロジェクトを作成できます。また、IntelliJ IDEA の機能を使用することもできます。

依存関係を追加する

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)
}