snp-sync-batch/SWAGGER_GUIDE.md

Swagger API 문서화 가이드

버전: 1.1.0 프로젝트: SNP Sync Batch - 해양 데이터 동기화 배치 시스템

---

Swagger UI 접속 정보

접속 URL

Swagger UI:        http://localhost:8051/snp-sync/swagger-ui/index.html
API 문서 (JSON):   http://localhost:8051/snp-sync/v3/api-docs
API 문서 (YAML):   http://localhost:8051/snp-sync/v3/api-docs.yaml

환경별 접속 URL

환경	URL
로컬 개발	http://localhost:8051/snp-sync/swagger-ui/index.html
개발 서버	http://211.208.115.83:8051/snp-sync/swagger-ui/index.html
운영 서버	http://211.208.115.83:8051/snp-sync/swagger-ui/index.html

---

제공되는 API

Batch Management API (/api/batch)

배치 작업 실행, 조회, 스케줄 관리 API

Job 실행 및 조회

Method	Endpoint	설명
GET	/api/batch/jobs	등록된 배치 작업 목록 조회
POST	/api/batch/jobs/{jobName}/execute	배치 작업 수동 실행
GET	/api/batch/jobs/{jobName}/executions	작업별 실행 이력 조회
GET	/api/batch/executions/{executionId}	실행 정보 조회
GET	/api/batch/executions/{executionId}/detail	Step 포함 상세 실행 정보 조회
POST	/api/batch/executions/{executionId}/stop	실행 중지

스케줄 관리

Method	Endpoint	설명
GET	/api/batch/schedules	스케줄 목록 조회
GET	/api/batch/schedules/{jobName}	특정 작업 스케줄 조회
POST	/api/batch/schedules	스케줄 생성
PUT	/api/batch/schedules/{jobName}	스케줄 수정
DELETE	/api/batch/schedules/{jobName}	스케줄 삭제
PATCH	/api/batch/schedules/{jobName}/toggle	스케줄 활성화/비활성화

대시보드 및 타임라인

Method	Endpoint	설명
GET	/api/batch/dashboard	대시보드 데이터 조회
GET	/api/batch/timeline	타임라인 데이터 조회
GET	/api/batch/timeline/period-executions	기간별 실행 이력 조회

---

API 테스트 예시

1. 배치 작업 목록 조회

GET http://localhost:8051/snp-sync/api/batch/jobs

예상 응답:

[
  "shipDetailSyncJob",
  "codeDataSyncJob",
  "eventDataSyncJob",
  "facilityDataSyncJob",
  "pscDataSyncJob",
  "riskDataSyncJob",
  "shipComplianceDataSyncJob",
  "anchorageCallSyncJob",
  "lastPositionUpdateJob"
]

2. 배치 작업 실행

POST http://localhost:8051/snp-sync/api/batch/jobs/shipDetailSyncJob/execute

예상 응답:

{
  "success": true,
  "message": "Job started successfully",
  "executionId": 1
}

3. 실행 이력 조회

GET http://localhost:8051/snp-sync/api/batch/jobs/shipDetailSyncJob/executions

4. 스케줄 생성

POST http://localhost:8051/snp-sync/api/batch/schedules
Content-Type: application/json

{
  "jobName": "shipDetailSyncJob",
  "cronExpression": "0 0 * * * ?",
  "description": "선박 정보 매시간 동기화"
}

5. 스케줄 활성화/비활성화

PATCH http://localhost:8051/snp-sync/api/batch/schedules/shipDetailSyncJob/toggle
Content-Type: application/json

{
  "active": false
}

---

Swagger 어노테이션 가이드

주요 어노테이션

1. @Tag - API 그룹화

@Tag(name = "Batch Management API", description = "배치 작업 실행 및 스케줄 관리 API")
public class BatchController { }

2. @Operation - 엔드포인트 문서화

@Operation(
    summary = "배치 작업 실행",
    description = "지정된 배치 작업을 즉시 실행합니다"
)

3. @Parameter - 파라미터 설명

@Parameter(description = "실행할 배치 작업 이름", required = true, example = "shipDetailSyncJob")
@PathVariable String jobName

4. @ApiResponses - 응답 정의

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "작업 실행 성공"),
    @ApiResponse(responseCode = "500", description = "작업 실행 실패")
})

신규 Controller에 Swagger 적용

@RestController
@RequestMapping("/api/custom")
@RequiredArgsConstructor
@Tag(name = "Custom API", description = "커스텀 API")
public class CustomController {

    @Operation(summary = "커스텀 조회", description = "특정 조건으로 데이터를 조회합니다")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "조회 성공"),
        @ApiResponse(responseCode = "500", description = "서버 오류")
    })
    @GetMapping("/data")
    public ResponseEntity<Map<String, Object>> getData(
            @Parameter(description = "조회 조건", required = true)
            @RequestParam String condition) {
        // 구현...
    }
}

---

문제 해결

Swagger UI 접속 불가 (404)

1. 애플리케이션이 실행 중인지 확인
2. 포트(8051)와 context-path(/snp-sync) 확인
3. 다음 URL 시도:
   • http://localhost:8051/snp-sync/swagger-ui/index.html
   • http://localhost:8051/snp-sync/swagger-ui.html

특정 엔드포인트가 보이지 않음

1. @RestController 어노테이션 확인
2. @RequestMapping 경로 확인
3. Controller가 com.snp.batch 패키지 하위에 있는지 확인
4. 애플리케이션 재시작

---

관련 파일

src/main/java/com/snp/batch/
├── global/config/SwaggerConfig.java           # Swagger 설정
├── global/controller/BatchController.java     # Batch Management API
└── common/web/controller/BaseController.java  # 공통 CRUD Base Controller

참고 자료

• Springdoc OpenAPI
• OpenAPI 3.0 Annotations