Skip to content
Server Plugin

OpenAPI

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

コード例: json-kotlinx-openapi

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

Ktorを使用すると、OpenAPI仕様に基づいてOpenAPIドキュメントを提供できます。

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

どちらの場合も、OpenAPIプラグインがサーバー上で仕様を組み立て、ドキュメントをHTMLとしてレンダリングします。

依存関係の追加 ​

  • OpenAPIドキュメントを提供するには、ビルドスクリプトにktor-server-openapiアーティファクトを追加する必要があります:

    kotlin
    implementation(ktorLibs.server.openapi)
    上記のコードスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
    groovy
    implementation 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依存関係を追加します:

    kotlin
    implementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")
    groovy
    implementation "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をレンダリングします:

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

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

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

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

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

このモードでは、OpenAPIプラグインがルーティングツリーから直接仕様を組み立てます:

kotlin
 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()を使用します:

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

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

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

ドキュメントレンダラーの設定 ​

デフォルトでは、ドキュメントはStaticHtml2Codegenを使用してレンダリングされます。

別のレンダラーを使用するには、codegenプロパティに割り当てます:

kotlin
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のままにしてください。