HYOJIN
744cc02f36
mda-snp-batch 기반으로 snp-sync-batch 프로젝트 생성 - 프론트엔드: Thymeleaf → React + TypeScript + Vite + Tailwind CSS 전환 - 컨텍스트: /snp-sync, 포트 8051 - 재수집(Recollection) 관련 코드 제거 - displayName → job_schedule.description 기반으로 전환 - 누락 API 추가 (statistics, jobs/detail, executions/recent) - 실행 이력 조회 속도 개선 (JDBC 경량 쿼리) - 스케줄 CRUD API 메서드 매핑 수정 (PUT/DELETE) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
225 lines
5.8 KiB
Markdown
225 lines
5.8 KiB
Markdown
# 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)
|