Server Plugin

OpenAPI

必須の依存関係: io.ktor:ktor-server-openapi

コード例: json-kotlinx-openapi

Nativeサーバー

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

のサポート: ✖️

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

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

• 既存のYAMLまたはJSONファイルを提供する。
• OpenAPIコンパイラ拡張およびランタイムAPIを使用して、ランタイムに仕様を生成する。

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

依存関係の追加

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

  Gradle (Kotlin)Gradle (Groovy)Maven

• オプションで、コードジェネレーターをカスタマイズしたい場合は、swagger-codegen-generators 依存関係を追加します。

  Gradle (Kotlin)Gradle (Groovy)Maven

  $swagger_codegen_version は、swagger-codegen-generators アーティファクトの必要なバージョン（例：1.0.36）に置き換えることができます。

Ktor 3.4.0では、OpenAPI プラグインは ktor-server-routing-openapi 依存関係を必要とします。 これは意図的な破壊的変更ではなく、Ktor 3.4.1で修正される予定です。 ランタイムエラーを避けるため、Ktor 3.4.0を使用している場合は手動で依存関係を追加してください。

静的な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の設定

デフォルトでは、ドキュメントは StaticHtml2Codegen を使用してレンダリングされます。openAPI {} ブロック内でレンダラーをカスタマイズできます。

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