Troubleshooting
생성 파일이 없거나 route/type이 누락될 때 설정과 지원 코드 모양을 순서대로 확인합니다.
확인 순서
• @Profile("local")이 실제 실행 profile에 포함되어 있는지 확인합니다.
• runner.start() 예외가 local console에서 발생하지 않았는지 확인합니다.
• rootPath, routerPackage, entityPackage, handlerOutputDir가 dot/slash 변환 후 올바른 위치인지 확인합니다.
• 생성 source directory가 IDE와 build tool source set에 포함되어 있는지 확인합니다.
• 외부 공통 모듈 type은 decompile jar class 또는 source classpath에 추가합니다.
• RouterFunction이 지원되는 fluent route/nest와 handler method reference 형태인지 확인합니다.
dot path와 slash path
Config는 여러 path 입력에서 .을 /로 정규화합니다. package 문자열과 filesystem path를 혼용할 수 있지만, src.main.java.com.example...처럼 전체 output path를 넣는 설정과 com.example... package만 넣는 설정의 차이를 확인해야 합니다.
경로 설정 재현
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 참조를 가진 최소 라우트 하나로 재현하고 생성 파일을 확인한 다음 기존 라우트를 추가합니다. swagger.json이 존재하는 것만으로 완료로 판단하지 말고 paths 안에 요청 경로와 HTTP method가 있는지 실제 응답 계약과 비교하세요.
무한 재생성
Swagger writer는 내용이 바뀔 때만 파일을 씁니다. 그럼에도 반복 generation이 발생하면 output 파일이 watchDirectory 안에 포함됐는지, formatter나 다른 watcher가 generated source를 계속 바꾸는지 확인하세요.