# API Openapi Diff

> OpenAPI(Swagger) 명세의 차이를 분석하고, Breaking Change 여부를 판정하여 안전한 버전 업그레이드 계획을 수립한다.

- Skill: `gaebalai-claude-code-kit-ko/api-openapi-diff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/api-openapi-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/api-openapi-diff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/api-openapi-diff

---


당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 목적

OpenAPI(Swagger) 명세의 신·구 버전을 비교하여 구조적 차이를 분석하고, Breaking Change(호환성 파괴 변경)를 식별한다.  
변경 사항을 **Breaking / Non-breaking / Addition / Removal**로 분류하고, Breaking Change에 대해서는 영향 범위 분석과 단계적 대응 계획을 제시한다.  
API 후방 호환성을 유지하면서 안전하게 버전 업그레이드할 수 있도록 의사결정 근거를 제공한다.

## 입력

- 구 버전 및 신 버전 OpenAPI 명세 파일 (YAML/JSON) 또는 API 코드베이스 (필수)
- 비교 대상 git 브랜치/태그/커밋 (선택)
- 영향을 받는 클라이언트 정보 (선택)
- 마이그레이션 일정 제약 (선택)
- 정보가 부족하면 사용자에게 질의할 것

## 절차

1. **OpenAPI 명세 식별 및 로딩**
   - Glob으로 명세 파일 탐색 (`openapi.*`, `swagger.*`, `api-spec.*`)
   - Read로 파일 로딩
   - git 관리 환경일 경우 `git diff`로 변경 내용 확보
   - `$ref`가 존재할 경우 참조 스키마까지 추적

2. **구조적 차이 분석**
   - Path 레벨 변경 탐지:
     - 추가 / 삭제 / 변경
   - 각 Path에 대해:
     - HTTP 메서드 추가/삭제
     - 요청 파라미터 변경 (타입, required 여부)
     - Request Body 스키마 변경
     - Response 스키마 변경
     - Status Code 변경
   - components.schemas / parameters / responses 변경 확인
   - securitySchemes 변경 확인

3. **Breaking Change 판정 기준 적용**

   ### Breaking Change
   - 엔드포인트 삭제
   - 필수 파라미터화 (optional → required)
   - 필드 타입 변경
   - Response 필드 삭제
   - enum 값 제거
   - URL 경로 변경
   - 인증 방식 변경

   ### Non-breaking
   - 신규 엔드포인트 추가
   - optional 파라미터 추가
   - Response 필드 추가
   - enum 값 추가
   - description 변경

   ### 주의 필요 변경
   - default 값 변경
   - nullable 변경
   - example 변경
   → 개별 영향 분석 필요

4. **영향 범위 평가**
   - Breaking Change별 영향 엔드포인트 정의
   - Grep으로 코드 내 호출 지점 탐색
   - 영향도 평가:
     - 즉시 런타임 오류
     - 데이터 정합성 위험
     - 기능 저하
   - 변경 간 의존성 분석

5. **수정 전략 수립**
   - 호환성 유지 전략:
     - Deprecated 유지 후 점진 제거
     - 버전 분리 (`/v1` 유지 + `/v2` 추가)
     - Feature flag 전략
   - 단계별 마이그레이션 계획 수립
   - 롤백 전략 명시

6. **릴리스 전 검증 체크리스트 작성**
   - Breaking Change 보호 조치 여부
   - 문서 및 SDK 동기화 여부
   - 모니터링 설정 여부
   - 롤백 시나리오 점검

## 출력 포맷

```markdown
## OpenAPI 차이 분석 리포트

### 비교 대상
- **구 버전**: [파일/태그/커밋]
- **신 버전**: [파일/태그/커밋]
- **분석 일자**: [날짜]

### 변경 요약

| 분류 | 건수 |
|------|------|
| Breaking Change | X건 |
| Non-breaking Change | X건 |
| Addition | X건 |
| Removal | X건 |

### Breaking Change 상세

#### BREAKING-001: [변경 요약]

- **엔드포인트**: [METHOD PATH]
- **변경 내용**: [구체적 설명]
- **영향 범위**: [클라이언트 영향]
- **심각도**: Critical/High/Medium
- **권장 대응 전략**: [호환성 레이어 / 버전 분리 등]

**구 명세**
```yaml
[이전 스펙 일부]
```
**신 명세**:
```yaml
[변경 후 스펙 일부]
```

#### BREAKING-002: [변경 요약]
(이하 동일하게 반복한다)

### Non-breaking 변경

| 엔드포인트         | 변경 내용 | 유형    |
| ------------- | ----- | ----- |
| [METHOD PATH] | [설명]  | 추가/확장 |

### 영향 분석
| 변경 ID        | 영향 유형          | 런타임 오류 | 데이터 위험 | 기능 저하 |
| ------------ | -------------- | ------ | ------ | ----- |
| BREAKING-001 | 파라미터 required화 | Yes    | No     | Yes   |

### 마이그레이션 계획

#### Phase 1: 호환성 계층 도입 (권장: X주)
- [ ] 기존 필드 deprecated 표시
- [ ] 신규 필드 병행 제공

#### Phase 2: 클라이언트 전환 기간 (권장: X주)
- [ ] SDK 업데이트
- [ ] 문서 배포
- [ ] 공지 발송

#### Phase 3: 구 스펙 제거
- [ ] 접근 로그 모니터링
- [ ] 제거 후 장애 모니터링 강화

### 릴리스 전 체크리스트

- [ ] 모든 Breaking Change에 대응 전략 적용 완료
- [ ] 클라이언트 마이그레이션 가이드 작성 완료
- [ ] 구 버전 접근 모니터링 설정 완료
- [ ] 롤백 절차 검증 완료
- [ ] API 문서 최신화 완료
```

## 안전 유의사항

- 명세 파일 분석만 수행하며 수정은 하지 않는다.
- `git diff` 외의 git 명령은 사용하지 않는다.
- 인증 정보가 명세에 포함되어 있을 경우 마스킹한다.
- Breaking Change 발견 시 반드시 경고하고 즉시 릴리스하지 않도록 유도한다.
- 운영 환경 API 호출 테스트는 수행하지 않는다.

---

## 종료 조건

위 포맷에 맞는 차이 분석 리포트를 출력하면 종료한다.  
모든 변경 사항이 Breaking / Non-breaking / Addition / Removal로 분류되어야 하며, Breaking Change에는 대응 전략과 단계별 마이그레이션 계획이 포함되어야 한다.  
실제 명세 수정은 사용자 지시를 기다린다.