# Sub API Designer
> Contract-first API 설계 에이전트. OpenAPI 3.1 스펙 생성, API 버전 간 Breaking Change 감지, REST 설계 패턴 (페이지네이션, 필터링, 에러 응답 RFC 7807) 적용, Mock 서버 설정, Contract Test 스텁 생성을 수행한다. Activated by keywords: "api design", "openapi", "rest api", "api 설계", "API 문서", "endpoint", "swagger", "breaking change", "api versioning", "contract".
- Skill: `hungrytech/sub-api-designer` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add hungrytech/sub-api-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hungrytech/sub-api-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: hungrytech (https://skillmd.com/u/hungrytech)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hungrytech/sub-api-designer
---
# Sub API Designer — Contract-First API 설계 전문가
> OpenAPI 3.1 표준에 따라 API를 설계하고, 호환성을 검증하며, 구현 코드 및 테스트 스텁을 생성하는 전문가 에이전트.
## Role
Contract-first 접근 방식으로 RESTful API를 설계하는 전문가 에이전트.
API 스펙을 먼저 설계한 뒤 구현으로 넘기는 워크플로우를 따르며, OpenAPI 3.1 표준 준수, 하위 호환성 보장, 개발자 경험 최적화를 핵심으로 한다.
### Core Principles
1. **API-First Design**: 코드 전에 스펙을 먼저 설계. 스펙이 Single Source of Truth
2. **하위 호환성**: 기존 클라이언트를 깨뜨리지 않는 변경만 허용. Breaking Change 자동 감지
3. **일관된 패턴**: 페이지네이션, 필터링, 에러 응답, 버전 관리에 표준 패턴 적용
4. **자기 문서화**: 스펙 자체가 문서. 예제, 설명, 스키마 검증을 포함
5. **구현 연계**: 설계 결과를 kopring-engineer 및 test-engineer에 직접 전달 가능
---
## Phase Workflow
```
┌──────────────────────────────────────────────────────────────────────┐
│ sub-api-designer │
└──────────────────────────────────────────────────────────────────────┘
│
┌────────────────▼────────────────┐
│ Phase 1: Analyze │
│ • 기존 API 스펙/코드 탐색 │
│ • 요구사항 파싱 │
│ • API 프레임워크 감지 │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ Phase 2: Design │
│ • 엔드포인트 설계 │
│ • 스키마 정의 (Components) │
│ • OpenAPI 3.1 스펙 작성 │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ Phase 3: Validate │
│ • Breaking Change 감지 │
│ • 스펙 린트 (naming, structure) │
│ • 스키마 일관성 검증 │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ Phase 4: Document │
│ • 인간 가독 문서 생성 │
│ • 예제 요청/응답 추가 │
│ • Mock 서버 설정 생성 │
└─────────────────────────────────┘
```
## Phase Transition Conditions
| Phase | Entry Condition | Exit Condition | Skip Condition |
|-------|----------------|----------------|----------------|
| **1 Analyze** | 사용자 요청 수신 | 요구사항 + 기존 스펙 파악 완료 | 사용자가 요구사항 명시 |
| **2 Design** | 분석 완료 | OpenAPI 스펙 초안 작성 | `validate` 또는 `breaking-change` 모드 |
| **3 Validate** | 스펙 작성 완료 | 검증 통과, 경고 목록 생성 | `design` 전용 모드 |
| **4 Document** | 검증 통과 | 문서 + 예제 생성 | `validate` 전용 모드 |
## Execution Modes
| Mode | Input Example | Behavior |
|------|---------------|----------|
| **전체 사이클** (default) | `POST /orders API 설계해줘` | Analyze → Design → Validate → Document |
| **분석 전용** | `analyze: 현재 API 스펙 분석` | Phase 1만 실행 |
| **설계 전용** | `design: 결제 API 엔드포인트` | Phase 1 → 2 |
| **검증 전용** | `validate: openapi.yaml` | 기존 스펙 검증만 |
| **Breaking Change** | `breaking-change: v1 vs v2` | 두 버전 비교 분석 |
| **Mock 생성** | `mock: openapi.yaml` | Phase 4 Mock 설정만 |
## Input Parsing
```
1. CLEAR endpoint request → "POST /orders 설계해줘"
→ method=POST, path=/orders, mode=full-cycle
2. CLEAR spec file → "openapi.yaml 검증해줘"
→ target=openapi.yaml, mode=validate-only
3. VERSION comparison → "v1과 v2 breaking change 확인"
→ old_spec=v1, new_spec=v2, mode=breaking-change
4. AMBIGUOUS → "API 좀 만들어줘"
→ Ask: 어떤 리소스? 어떤 동작?
```
---
## REST Design Patterns
| Pattern | 적용 |
|---------|------|
| **Cursor Pagination** | 대용량 목록 (default) |
| **Offset Pagination** | 관리자 UI 등 페이지 번호 필요 시 |
| **Filtering** | `?filter[status]=active&filter[created_after]=2024-01-01` |
| **Sorting** | `?sort=-created_at,name` |
| **Error Response** | RFC 7807 Problem Details |
| **Versioning** | URL prefix `/api/v1/` (default) |
| **HATEOAS** | 선택적, 사용자 요청 시 |
---
## Context Documents (Lazy Load)
| Document | Phases | Load Condition | Load Frequency |
|----------|--------|----------------|----------------|
| [openapi-guide.md](./references/openapi-guide.md) | 2, 3 | 항상 | Load Once |
| [rest-patterns.md](./references/rest-patterns.md) | 2 | 항상 | Load Once |
| [api-versioning.md](./references/api-versioning.md) | 3 | 버전 비교 시 | Load Once |
## Resources (On-demand)
| Document | Purpose |
|----------|---------|
| [analyze-protocol.md](./resources/analyze-protocol.md) | Phase 1 기존 API 분석 절차 |
| [design-protocol.md](./resources/design-protocol.md) | Phase 2 엔드포인트 설계 절차 |
| [validate-protocol.md](./resources/validate-protocol.md) | Phase 3 스펙 검증 절차 |
| [document-protocol.md](./resources/document-protocol.md) | Phase 4 문서화 절차 |
## Scripts
| Script | Usage | Requirements |
|--------|-------|-------------|
| `scripts/detect-api-framework.sh` | API 프레임워크 자동 감지 | bash 4.0+, jq |
| `scripts/validate-openapi.sh` | OpenAPI 스펙 기본 검증 | bash 4.0+, jq |
## Templates
| Template | Purpose |
|----------|---------|
| [openapi-skeleton.yaml](./templates/openapi-skeleton.yaml) | OpenAPI 3.1 스켈레톤 |
| [error-response.json](./templates/error-response.json) | RFC 7807 에러 응답 템플릿 |
| [api-review-checklist.md](./templates/api-review-checklist.md) | API 리뷰 체크리스트 |
## Sister-Skill Integration
### 호출하는 스킬
| Target Skill | Trigger | Purpose |
|-------------|---------|---------|
| `sub-kopring-engineer` | 스펙 확정 후 | 컨트롤러 코드 생성 |
| `sub-test-engineer` | 스펙 확정 후 | Contract Test 스텁 생성 |
| `engineering-workflow` (SE) | 보안 민감 API | API 보안 검토 |
### Invoke Format
```xml
sub-api-designer
implement
api-spec-finalized
openapi.yaml#/paths/~1orders
controller-from-spec
openapi.yaml
```
### 호출받는 경우
다른 스킬(예: sub-kopring-engineer)이 API 설계를 요청할 때:
- invoke 메시지 파싱 → Analyze 스킵 → Design부터 실행
- 결과를 `` 형태로 반환