---
name: swagger-update
version: 2.0.0
description: 스웨거에서 최신 API 스펙을 가져와 도메인별 분리 저장하고 코드 변경점을 분석
user-invocable: true
---

# API 스펙 동기화

스웨거(dev 서버)에서 최신 OpenAPI 스펙을 가져와 `.claude/api-spec/` 도메인별 파일로 분리 저장하고, 기존 코드와의 차이를 분석합니다.

## 사용법

```
/swagger-update                  # 전체 스펙 동기화 + 변경점 분석
/swagger-update <keyword>        # 특정 도메인만 비교 (예: referral, users, matches)
```

## 파일 구조

```
.claude/api-spec/
├── auth.json          # login, logout, register, terms
├── users.json         # users
├── profiles.json      # profiles
├── matches.json       # matches
├── referral.json      # referral-code
├── payments.json      # payments, cash-products
├── notifications.json # notifications
├── settings.json      # settings
├── values.json        # valuePicks, valueTalks
├── block.json         # block, blockContacts, reports
├── sse.json           # sse
└── admin.json         # admin
```

각 파일은 `$ref`가 모두 해소된 상태로, 바로 읽어서 필드 확인이 가능합니다.

---

## 실행 단계

### 1. 최신 스펙 가져오기

스웨거 dev 서버에서 최신 스펙을 다운로드합니다:

```bash
curl -s https://dev-api-v2.puzzly.site/v3/api-docs | python3 -m json.tool > /tmp/api-spec-latest.json
```

**IF** 다운로드 실패:
→ 네트워크 또는 서버 상태 확인 안내 후 종료

### 2. 도메인별 분리 및 기존 스펙과 비교

최신 스펙을 도메인별로 분리합니다:

```bash
python3 .claude/scripts/split-api-spec.py /tmp/api-spec-latest.json /tmp/api-spec-new/
```

기존 `.claude/api-spec/` 파일들과 `/tmp/api-spec-new/` 파일들을 비교합니다.

**비교 항목**:
- 새로 추가된 엔드포인트
- 삭제된 엔드포인트
- 변경된 엔드포인트 (request/response 필드 차이)

**키워드 인자가 있는 경우**:
→ 해당 키워드와 매칭되는 도메인 파일만 비교 (예: `referral` → `referral.json`)

**IF** 기존 도메인 파일이 없는 경우:
→ 비교 건너뛰고 Step 3으로 진행

### 3. 로컬 스펙 업데이트

```bash
python3 .claude/scripts/split-api-spec.py /tmp/api-spec-latest.json .claude/api-spec/
```

### 4. 변경점 분석 보고

변경된 엔드포인트의 구체적인 필드 차이를 보고합니다:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 API 스펙 동기화 결과
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📥 업데이트된 도메인: referral.json, users.json

🆕 새 엔드포인트:
  • METHOD /path — summary

🔄 변경된 엔드포인트:
  • METHOD /path
    - 필드 추가: fieldName (type)
    - 필드 제거: fieldName
    - 타입 변경: fieldName (oldType → newType)

🗑️ 삭제된 엔드포인트:
  • METHOD /path

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 5. 코드 영향도 분석

변경된 엔드포인트에 대해 기존 프로젝트 코드와 매칭하여 수정이 필요한 파일을 식별합니다.

**매칭 방법**:
1. 변경된 API path를 Endpoint 파일에서 검색
2. 매칭된 Endpoint의 관련 DTO, Repository, UseCase, Entity 파일 추적
3. 구체적 필드 차이와 현재 코드 비교

```
📂 코드 영향도:

• METHOD /path
  ├── Endpoint:   {file}
  ├── DTO:        {file} — {변경 필요 내용}
  ├── Entity:     {file} — {변경 필요 내용}
  ├── Repository: {file} — {변경 필요 내용}
  └── UseCase:    변경 없음
```

**IF** 변경 없음:
→ "스펙 변경 없음. 로컬이 최신 상태입니다." 보고 후 종료

### 6. 수정 제안

→ AskUserQuestion 도구로 질문:

```
변경된 코드를 바로 수정할까요?

1. 바로 수정 — 영향받는 파일 모두 업데이트
2. 보고만 — 변경점 확인 후 직접 수정
```

**바로 수정 선택 시**:
→ data-layer.md 규칙에 따라 DTO, Entity, Repository 등 수정 진행

---

## API 스펙 조회 방법

코드 작성 시 API 스펙을 확인할 때는 도메인 파일을 직접 읽습니다:

```
# referral API 확인
Read .claude/api-spec/referral.json

# matches API 확인
Read .claude/api-spec/matches.json
```

---

## 엣지 케이스

### Case: 스웨거에 schema 없이 example만 있는 경우
→ example에서 필드명과 타입을 추론하여 `responseExample` 필드로 저장

### Case: 기존 도메인 파일이 없는 경우
→ 비교 없이 최신 스펙 분리 저장 + 전체 도메인 목록 보고

### Case: 네트워크 오류
→ "스웨거 서버에 접근할 수 없습니다. VPN 또는 서버 상태를 확인해주세요." 안내