トラブルシューティング
生成ファイルがない場合やroute/typeが欠落している場合、設定とサポートコードの形を順番に確認します。
確認順序
• @Profile("local")が実際の実行プロファイルに含まれているか確認します。
• runner.start()の例外がローカルコンソールで発生していないか確認します。
• rootPath, routerPackage, entityPackage, handlerOutputDirがドット/スラッシュ変換後に正しい位置にあるか確認します。
• 生成されたソースディレクトリがIDEとビルドツールのソースセットに含まれているか確認します。
• 外部共通モジュールタイプは、デコンパイルしたjarクラスまたはソースクラスパスに追加します。
• RouterFunctionがサポートされているフルーエントルート/ネストとハンドラメソッドリファレンス形式であるか確認します。
ドットパスとスラッシュパス
Configは複数のパス入力で.を/に正規化します。パッケージ文字列とファイルシステムパスを混用できますが、src.main.java.com.example...のように全体の出力パスを入れる設定とcom.example...パッケージのみを入れる設定の違いを確認する必要があります。
パス設定の再現
import com.byeolnaerim.watch.route.HandlerGenerator;
var handlerConfig = HandlerGenerator.Config.builder()
.rootPath("src/main/java")
.routerPackage("com.example.web.router")
.handlerPackage("com.example.web.handler")
.handlerOutputDir("src/main/java/com/example/web/handler")
.build();
System.out.println(handlerConfig.routerDir());
// src/main/java/com/example/web/router/プロジェクトルートで実行し、表示された routerDir にルーターのソースがあるか確認します。routerPackage に src/main/java まで含めるとパスが重複します。この設定を runner の handlerConfig に渡し、Quick Start の local profile で実行します。handlerPackage は Java パッケージ名、handlerOutputDir は実際の出力ディレクトリです。
test -d src/main/java/com/example/web/router
find src/main/java/com/example/web/handler -name '*.java'
# Quick Start swaggerOutputFile:
test -s src/main/resources/static/swagger.jsonパスが正しいのに出力がない場合は、runner.start() の最初の例外から確認します。handler::method 参照を使う最小のルート1つで再現し、生成ファイルを確認してから既存のルートを追加します。swagger.json の存在だけで完了とせず、paths 内のリクエストパスと HTTP method を実際のレスポンス契約と照合してください。
無限再生成
Swaggerライターは内容が変更されたときのみファイルを書き込みます。それでも繰り返し生成が発生する場合は、出力ファイルがwatchDirectory内に含まれているか、フォーマッタや他のウォッチャーが生成されたソースを継続的に変更しているか確認してください。