Ktor で構築した REST API に、Swagger UI を組み込む方法を紹介します。
OpenAPI プラグインと Swagger UI プラグインを使うことで、API ドキュメントの生成と Web UI 表示が簡単に実現できます。

参考リンク

導入手順

1. 依存関係を追加

プロジェクトの build.gradle.kts に以下を追加します。

implementation("io.ktor:ktor-server-openapi:<ktor_version>")
implementation("io.ktor:ktor-server-swagger:<ktor_version>")

※ には使用中のバージョンを指定してください。

2. プラグインをインストール

Application.module に以下のコードを追加します。

install(OpenAPI) {
    info {
        title = "My API"
        version = "1.0"
        description = "Sample API with Swagger UI"
    }
}

install(SwaggerUI) {
    path = "swagger"
}

/openapi.json: OpenAPI 仕様の JSON が出力されます
/swagger: Swagger UI が表示されます

3. CORS の設定（重要）

Swagger UI を使う場合、ブラウザ上で OpenAPI JSON を取得する際に CORS に引っかかることがあります。
そのため、以下のように CORS を有効化する必要がありました。

install(CORS) {
    anyHost() // 開発・テスト用途のみ推奨
    allowHeader(HttpHeaders.ContentType)
}

4. 必要に応じてアノテーションの追加

ルーティングに @OpenAPIRoute などのアノテーションを付与することで、
API 定義により詳しい情報を追加できます。

※ Ktor の Context DSL では一部の情報が自動反映されない場合があります

本記事では @OpenAPIRoute などのアノテーションは使用していませんが、
より詳細なスキーマ定義やエンドポイント説明を記述したい場合に利用できます。

5. 動作確認

アプリを起動後、以下にアクセスします：

おまけ: モバイル開発検証用の公開 API （Free）

現在、Free で使える検証用 API を公開しています。
Kotlin Multiplatform（KMP）アプリの初期開発時に API 通信の検証用に使っていました。

https://freeapi.dignicate.com/swagger

都度変わることがあるので注意

参考 PR

GitHub で公開しているレポジトリの該当 PR は下記になります

https://github.com/dignicate/p30a-ktor/pull/7

補足：documentation.yaml について

OpenAPI プラグインを導入すると、documentation.yaml が生成されることがあります。
IDE（IntelliJ など）がルーティング定義などをもとに半自動的に作成してくれるため、手動で細かく書く必要はありません。
必要に応じて、このファイルを編集して API スキーマを明示することも可能です。

まとめ

Ktor × Swagger UI 連携は、公式プラグインで簡単に導入可能
API ドキュメントを視覚的に表示・共有できる
小〜中規模プロジェクトにもおすすめ