Skip to content
Server Plugin

Swagger UI

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

コード例: json-kotlinx-openapi

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

Ktorを使用すると、OpenAPI仕様に基づいてプロジェクト用のSwagger UIを生成し、配信することができます。 Swagger UIを使用すると、ブラウザから直接APIエンドポイントを可視化し、対話的に操作できます。

OpenAPI仕様は、次のいずれかの方法で提供できます。

依存関係の追加 ​

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

kotlin
implementation(ktorLibs.server.swagger)
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
groovy
implementation ktorLibs.server.swagger
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-swagger-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

静的なOpenAPIファイルの使用 ​

既存のOpenAPI仕様ファイルからSwagger UIを配信するには、swaggerUI() 関数を使用してファイルの場所を指定します。

次の例では、swagger パスに GET エンドポイントを作成し、提供されたOpenAPI仕様ファイルからSwagger UIをレンダリングします。

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

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

プラグインはまずアプリケーションのリソース内で仕様を検索します。見つからない場合は、java.io.File を使用してファイルシステムから読み込みを試みます。

ランタイムOpenAPIメタデータの生成 ​

静的ファイルに依存する代わりに、OpenAPIコンパイラプラグインとルートアノテーションによって生成されたメタデータを使用して、実行時にOpenAPI仕様を生成できます。

kotlin
swaggerUI("/swaggerUI") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing(ContentType.Application.Json) {
        routingRoot.descendants()
    }
}

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

OpenAPIコンパイラ拡張機能およびランタイムAPIの詳細については、OpenAPI仕様の生成を参照してください。

Swagger UIの設定 ​

swaggerUI {} 設定ブロックを使用すると、OpenAPIドキュメントの設定やSwagger UIのカスタマイズを行うことができます。

ドキュメントのメタデータを設定する ​

設定ブロック内でトップレベルのOpenAPIメタデータを直接定義できます。

たとえば、一般的なAPI情報を指定するには info を使用し、タグとその説明を定義するには tag() を使用します。

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

また、サーバー、セキュリティ要件、再利用可能なコンポーネント、外部ドキュメント、仕様拡張など、他のトップレベルのOpenAPIプロパティを設定することも可能です。

利用可能なすべてのオプションについては、SwaggerConfig APIリファレンスを参照してください。

Swagger UIのバージョンを設定する ​

デフォルトでは、Ktorは事前定義されたSwagger UIのバージョンを使用します。別のバージョンを使用するには、version プロパティを設定します。

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

OpenAPI 3.1.xドキュメントにはSwagger UI 5.xが必要ですが、Swagger UI 4.xはOpenAPI 3.0.xのみをサポートしています。

CORSの設定 ​

Swagger UIがAPIエンドポイントに正しくアクセスできるようにするには、まずクロスオリジンリソース共有(CORS)を設定する必要があります。

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

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