OpenAPI
必要な依存関係: io.ktor:ktor-server-openapi
コード例: json-kotlinx-openapi
ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✖️
Ktorを使用すると、OpenAPI仕様に基づいてOpenAPIドキュメントを提供できます。
OpenAPI仕様は、次のいずれかの方法で提供できます:
どちらの場合も、OpenAPIプラグインがサーバー上で仕様を組み立て、ドキュメントをHTMLとしてレンダリングします。
依存関係の追加
OpenAPIドキュメントを提供するには、ビルドスクリプトに
ktor-server-openapiアーティファクトを追加する必要があります:kotlinimplementation(ktorLibs.server.openapi)上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。groovyimplementation ktorLibs.server.openapi上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-openapi-jvm</artifactId> <version>${ktor_version}</version> </dependency>必要に応じて、コードジェネレーターをカスタマイズしたい場合は
swagger-codegen-generators依存関係を追加します:kotlinimplementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")groovyimplementation "io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version"xml<dependency> <groupId>io.swagger.codegen.v3</groupId> <artifactId>swagger-codegen-generators</artifactId> <version>${swagger_codegen_version}</version> </dependency>$swagger_codegen_versionは、必要なswagger-codegen-generatorsアーティファクトのバージョン(例:1.0.47)に置き換えることができます。
静的OpenAPIファイルの使用
既存の仕様からOpenAPIドキュメントを提供するには、OpenAPIドキュメントへのパスを指定してopenAPI()関数を使用します。
以下の例では、openapiパスにGETエンドポイントを作成し、提供されたOpenAPI仕様ファイルからSwagger UIをレンダリングします:
import io.ktor.server.plugins.openapi.*
// ...
routing {
openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml")
}プラグインはまずアプリケーションリソース内で仕様を検索します。見つからない場合は、java.io.Fileを使用してファイルシステムからのロードを試みます。
ランタイムOpenAPIメタデータの生成
静的ファイルに頼る代わりに、OpenAPIコンパイラプラグインとルートアノテーションによって生成されたメタデータを使用して、実行時にOpenAPI仕様を生成できます。
このモードでは、OpenAPIプラグインがルーティングツリーから直接仕様を組み立てます:
openAPI(path = "openapi") {
info = OpenApiInfo("My API", "1.0")
source = OpenApiDocSource.Routing {
routingRoot.descendants()
}
}これにより、アプリケーションの現在の状態を反映した、生成されたOpenAPIドキュメントに/openapiパスからアクセスできます。
OpenAPIコンパイラ拡張およびランタイムAPIの詳細については、OpenAPI仕様の生成を参照してください。
OpenAPIの設定
openAPI {}設定ブロックを使用すると、生成されるOpenAPIドキュメントと、Ktorがドキュメントをレンダリングする方法を設定できます。
ドキュメントメタデータの設定
トップレベルのOpenAPIメタデータは、設定ブロック内で直接定義できます。
たとえば、一般的なAPI情報を指定するにはinfoを使用し、タグとその説明を定義するにはtag()を使用します:
openAPI("openapi") {
info = OpenApiInfo("Books API from routes", "1.0.0")
tag(
name = "Books",
description = "Operations on books"
)
}また、サーバー、セキュリティ要件、再利用可能なコンポーネント、外部ドキュメント、仕様拡張など、他のトップレベルのOpenAPIプロパティを設定することもできます。
利用可能なすべてのオプションについては、OpenAPIConfig APIリファレンスを参照してください。
ドキュメントレンダラーの設定
デフォルトでは、ドキュメントはStaticHtml2Codegenを使用してレンダリングされます。
別のレンダラーを使用するには、codegenプロパティに割り当てます:
routing {
openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml") {
codegen = StaticHtmlCodegen()
}
}StaticHtmlCodegenおよびStaticHtml2CodegenはOpenAPI 3.0.xドキュメントのみをサポートしています。これらをOpenAPI 3.1ドキュメントで使用すると、不完全または不正確なHTMLが生成される可能性があります。OpenAPI 3.1の場合は、Swagger UI 5.xとともにswaggerUI()関数を使用してください。引き続きOpenAPIプラグインのHTMLレンダラーを使用する必要がある場合は、仕様をOpenAPI 3.0.3のままにしてください。
