# 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. 배치 작업 목록 조회

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

**예상 응답**:
```json
[
  "shipDetailSyncJob",
  "codeDataSyncJob",
  "eventDataSyncJob",
  "facilityDataSyncJob",
  "pscDataSyncJob",
  "riskDataSyncJob",
  "shipComplianceDataSyncJob",
  "anchorageCallSyncJob",
  "lastPositionUpdateJob"
]
```

### 2. 배치 작업 실행

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

**예상 응답**:
```json
{
  "success": true,
  "message": "Job started successfully",
  "executionId": 1
}
```

### 3. 실행 이력 조회

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

### 4. 스케줄 생성

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

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

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

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

{
  "active": false
}
```

---

## Swagger 어노테이션 가이드

### 주요 어노테이션

#### 1. `@Tag` - API 그룹화
```java
@Tag(name = "Batch Management API", description = "배치 작업 실행 및 스케줄 관리 API")
public class BatchController { }
```

#### 2. `@Operation` - 엔드포인트 문서화
```java
@Operation(
    summary = "배치 작업 실행",
    description = "지정된 배치 작업을 즉시 실행합니다"
)
```

#### 3. `@Parameter` - 파라미터 설명
```java
@Parameter(description = "실행할 배치 작업 이름", required = true, example = "shipDetailSyncJob")
@PathVariable String jobName
```

#### 4. `@ApiResponses` - 응답 정의
```java
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "작업 실행 성공"),
    @ApiResponse(responseCode = "500", description = "작업 실행 실패")
})
```

### 신규 Controller에 Swagger 적용

```java
@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](https://springdoc.org/)
- [OpenAPI 3.0 Annotations](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations)