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 アーティファクトを追加する必要があります。
implementation(ktorLibs.server.swagger)implementation ktorLibs.server.swagger<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をレンダリングします。
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 {} 設定ブロックを使用すると、OpenAPIドキュメントの設定やSwagger UIのカスタマイズを行うことができます。
ドキュメントのメタデータを設定する
設定ブロック内でトップレベルのOpenAPIメタデータを直接定義できます。
たとえば、一般的なAPI情報を指定するには info を使用し、タグとその説明を定義するには tag() を使用します。
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 プロパティを設定します。
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クライアントヘッダーを許可します。
install(CORS) {
anyHost()
allowHeader(HttpHeaders.ContentType)
}