From 508f35a21418bd6137e9891a3e63c0332431989e Mon Sep 17 00:00:00 2001 From: htlee Date: Thu, 19 Feb 2026 21:29:40 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Swagger=20UI=20=ED=98=84=ED=96=89?= =?UTF-8?q?=ED=99=94=20=E2=80=94=20=EC=84=9C=EB=B2=84=20URL,=20DTO=20@Sche?= =?UTF-8?q?ma,=20@Parameter=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SwaggerConfig: 서버 URL을 현행 환경(192.168.1.18:18090)으로 업데이트 - AbnormalTrackResponse: 13개 필드에 @Schema 어노테이션 추가 - AbnormalTrackStatsResponse: 7개 필드에 @Schema 어노테이션 추가 - GisController V1: minutes 파라미터 4곳에 @Parameter 추가 - BatchAdminController: step/details 엔드포인트에 @Operation 추가 Co-Authored-By: Claude Opus 4.6 --- .../domain/gis/controller/GisController.java | 4 +++ .../track/dto/AbnormalTrackResponse.java | 34 ++++++++++++++++--- .../track/dto/AbnormalTrackStatsResponse.java | 19 +++++++++-- .../global/config/SwaggerConfig.java | 6 ++-- .../controller/BatchAdminController.java | 4 ++- 5 files changed, 56 insertions(+), 11 deletions(-) diff --git a/src/main/java/gc/mda/signal_batch/domain/gis/controller/GisController.java b/src/main/java/gc/mda/signal_batch/domain/gis/controller/GisController.java index bcd73b5..bb00c86 100644 --- a/src/main/java/gc/mda/signal_batch/domain/gis/controller/GisController.java +++ b/src/main/java/gc/mda/signal_batch/domain/gis/controller/GisController.java @@ -38,6 +38,7 @@ public class GisController { @GetMapping("/haegu/vessel-stats") @Operation(summary = "해구별 선박 통계", description = "지정된 시간 동안의 해구별 선박 통계") public Map getHaeguVesselStats( + @Parameter(description = "조회 시간 범위 (분)", example = "60") @RequestParam(defaultValue = "60") int minutes) { return gisService.getHaeguVesselStats(minutes); } @@ -51,6 +52,7 @@ public class GisController { @GetMapping("/areas/vessel-stats") @Operation(summary = "영역별 선박 통계", description = "지정된 시간 동안의 영역별 선박 통계") public Map getAreaVesselStats( + @Parameter(description = "조회 시간 범위 (분)", example = "60") @RequestParam(defaultValue = "60") int minutes) { return gisService.getAreaVesselStats(minutes); } @@ -59,6 +61,7 @@ public class GisController { @Operation(summary = "해구별 선박 항적", description = "특정 해구의 선박 항적 조회") public List getHaeguTracks( @PathVariable Integer haeguNo, + @Parameter(description = "조회 시간 범위 (분)", example = "60") @RequestParam(defaultValue = "60") int minutes) { return gisService.getHaeguTracks(haeguNo, minutes); } @@ -67,6 +70,7 @@ public class GisController { @Operation(summary = "영역별 선박 항적", description = "특정 영역의 선박 항적 조회") public List getAreaTracks( @PathVariable String areaId, + @Parameter(description = "조회 시간 범위 (분)", example = "60") @RequestParam(defaultValue = "60") int minutes) { return gisService.getAreaTracks(areaId, minutes); } diff --git a/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackResponse.java b/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackResponse.java index 64c9808..eaf311a 100644 --- a/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackResponse.java +++ b/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackResponse.java @@ -1,5 +1,6 @@ package gc.mda.signal_batch.domain.track.dto; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.Builder; import lombok.Data; @@ -7,26 +8,51 @@ import java.math.BigDecimal; import java.time.LocalDateTime; import java.util.Map; -/** - * 비정상 궤적 응답 DTO - */ @Data @Builder +@Schema(description = "비정상 항적 응답") public class AbnormalTrackResponse { + + @Schema(description = "비정상 항적 ID", example = "12345") private Long id; + + @Schema(description = "선박 MMSI", example = "440001000") private String mmsi; + + @Schema(description = "집계 시간 버킷", example = "2026-02-19T12:00:00") private LocalDateTime timeBucket; + + @Schema(description = "비정상 유형 코드", example = "excessive_speed", + allowableValues = {"excessive_speed", "teleport", "excessive_acceleration", "gap_jump"}) private String abnormalType; + + @Schema(description = "비정상 유형 설명", example = "과속") private String typeDescription; + + @Schema(description = "비정상 상세 설명", example = "속도 150.0 knots 초과 (임계값: 100.0 knots)") private String abnormalDescription; + + @Schema(description = "이동 거리 (해리)", example = "5.32") private BigDecimal distanceNm; + + @Schema(description = "평균 속도 (knots)", example = "45.7") private BigDecimal avgSpeed; + + @Schema(description = "최대 속도 (knots)", example = "150.2") private BigDecimal maxSpeed; + + @Schema(description = "항적 포인트 수", example = "24") private Integer pointCount; + + @Schema(description = "원본 테이블", example = "t_vessel_tracks_5min") private String sourceTable; + + @Schema(description = "검출 일시", example = "2026-02-19T12:05:00") private LocalDateTime detectedAt; + + @Schema(description = "추가 상세 정보 (JSON)") private Map details; - // GeoJSON 형식의 궤적 (선택적) + @Schema(description = "GeoJSON 형식 항적 (선택적)") private Object trackGeoJson; } diff --git a/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackStatsResponse.java b/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackStatsResponse.java index 866402c..3c080ec 100644 --- a/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackStatsResponse.java +++ b/src/main/java/gc/mda/signal_batch/domain/track/dto/AbnormalTrackStatsResponse.java @@ -1,22 +1,35 @@ package gc.mda.signal_batch.domain.track.dto; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.Builder; import lombok.Data; import java.math.BigDecimal; import java.time.LocalDate; -/** - * 비정상 궤적 통계 응답 DTO - */ @Data @Builder +@Schema(description = "비정상 항적 일별 통계 응답") public class AbnormalTrackStatsResponse { + + @Schema(description = "통계 기준일", example = "2026-02-19") private LocalDate statDate; + + @Schema(description = "비정상 유형 코드", example = "excessive_speed") private String abnormalType; + + @Schema(description = "해당 유형 선박 수", example = "42") private Integer vesselCount; + + @Schema(description = "해당 유형 항적 수", example = "156") private Integer trackCount; + + @Schema(description = "총 포인트 수", example = "3840") private Integer totalPoints; + + @Schema(description = "평균 편차", example = "12.5") private BigDecimal avgDeviation; + + @Schema(description = "최대 편차", example = "150.2") private BigDecimal maxDeviation; } \ No newline at end of file diff --git a/src/main/java/gc/mda/signal_batch/global/config/SwaggerConfig.java b/src/main/java/gc/mda/signal_batch/global/config/SwaggerConfig.java index 43dd01f..b17412e 100644 --- a/src/main/java/gc/mda/signal_batch/global/config/SwaggerConfig.java +++ b/src/main/java/gc/mda/signal_batch/global/config/SwaggerConfig.java @@ -65,9 +65,9 @@ import org.springframework.context.annotation.Configuration; ) ), servers = { - @Server(url = "http://10.26.252.51:8090", description = "Development Server (QueryDB)"), - @Server(url = "http://10.26.252.39:8090", description = "Production Server"), - @Server(url = "http://localhost:8090", description = "Local Development Server") + @Server(url = "http://192.168.1.18:18090/signal-batch", description = "Production Server"), + @Server(url = "http://localhost:8090/signal-batch", description = "Local Development"), + @Server(url = "http://localhost:18090/signal-batch", description = "Local (Prod Port)") } ) public class SwaggerConfig { diff --git a/src/main/java/gc/mda/signal_batch/monitoring/controller/BatchAdminController.java b/src/main/java/gc/mda/signal_batch/monitoring/controller/BatchAdminController.java index bec4ffd..3c81f6f 100644 --- a/src/main/java/gc/mda/signal_batch/monitoring/controller/BatchAdminController.java +++ b/src/main/java/gc/mda/signal_batch/monitoring/controller/BatchAdminController.java @@ -412,7 +412,9 @@ public class BatchAdminController { * Step 실행 상세 */ @GetMapping("/step/details/{executionId}") - public ResponseEntity>> getStepDetails(@PathVariable Long executionId) { + @Operation(summary = "Step 실행 상세", description = "특정 Job 실행의 Step별 상세 정보 (상태, 읽기/쓰기 건수, 커밋/롤백 수 등)를 조회합니다") + public ResponseEntity>> getStepDetails( + @Parameter(description = "Job 실행 ID", example = "12345") @PathVariable Long executionId) { try { JobExecution jobExecution = jobExplorer.getJobExecution(executionId); if (jobExecution == null) { -- 2.45.2