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. 動作確認
アプリを起動後、以下にアクセスします：
- Swagger UI → http://localhost:8080/swagger
- OpenAPI JSON → http://localhost:8080/openapi.json
おまけ: モバイル開発検証用の公開 API （Free）
現在、Free で使える検証用 API を公開しています。
Kotlin Multiplatform（KMP）アプリの初期開発時に API 通信の検証用に使っていました。
都度変わることがあるので注意
参考 PR
GitHub で公開しているレポジトリの該当 PR は下記になります
補足：documentation.yaml について
OpenAPI プラグインを導入すると、documentation.yaml が生成されることがあります。
IDE（IntelliJ など）がルーティング定義などをもとに半自動的に作成してくれるため、手動で細かく書く必要はありません。
必要に応じて、このファイルを編集して API スキーマを明示することも可能です。
まとめ
- Ktor × Swagger UI 連携は、公式プラグインで簡単に導入可能
- API ドキュメントを視覚的に表示・共有できる
- 小〜中規模プロジェクトにもおすすめ