jh941213 인터페이스/API 문서 스킬
시스템 간 계약을 문서화한다. 명세는 Git이 단일 진실 소스(docs-as-code).
입력
$ARGUMENTS
산출물 맵
| 대상 | 산출물 | 위치 |
|---|---|---|
| REST API | OpenAPI 3.1 명세 | docs/api/openapi.yaml |
| 이벤트/메시지 인터페이스 | AsyncAPI 3.0 명세 | docs/api/asyncapi.yaml |
| API 구성도 (시스템 간 호출 관계) | C4 Container + 핵심 플로우별 시퀀스 다이어그램 | docs/api/README.md |
| 사람이 읽는 레퍼런스 | 엔드포인트별 마크다운 (기존 docs-writer의 api.md 형식 계승) | docs/api/reference.md |
| API 변경 이력 | breaking/non-breaking 구분 + deprecation 일정 | docs/api/CHANGELOG.md |
Spec-first vs Code-first 판단
- 여러 팀/외부가 계약을 소비 → spec-first:
docs/api/openapi.yaml을 먼저 작성·리뷰, 코드가 명세를 따른다 - 단일 팀 내부 서비스 → code-first 허용. 단, 코드에서 생성한 명세를 반드시 커밋하고 CI에서 diff (드리프트 게이트는 docs-ci 스킬이 설치)
- 어느 쪽이든 명세 파일이 레포에 존재해야 한다 — "코드가 곧 문서"는 인정하지 않음
OpenAPI 작성 규칙
- 코드에서 실제 라우트/스키마를 읽고 작성 — 추측 금지. 확인 불가한 필드는 TODO 주석으로 표시
operationId필수, 태그로 리소스 그룹화, 4xx/5xx 응답 포함- 예시(example)는 실제 동작하는 값으로
- 인증 스킴(
securitySchemes) 명시 - 이벤트 기반 인터페이스(큐, 웹소켓, 웹훅)는 OpenAPI에 우겨넣지 말고 AsyncAPI로 분리
API 구성도 + 흐름도
- 시스템 간 토폴로지: C4 Container 다이어그램 1개
- 핵심 플로우(인증, 주문 생성 등)마다 시퀀스 다이어그램 1개 — 문법은
../docs-architecture/references/mermaid-conventions.md공용 관례 사용 - 에러 경로(
alt블록)를 최소 1개 포함 — 행복 경로만 그리지 않는다
API CHANGELOG 규칙
## [v1.4.0] - 2026-07-27
### Breaking
- `GET /users` 응답에서 `nickname` 제거 → `profile.nickname` (마이그레이션: …)
### Added
- `POST /invoices/bulk`
### Deprecated
- `GET /v1/legacy-search` — 2026-10-01 sunset
- breaking 변경은 반드시 마이그레이션 경로를 함께 기술
- oasdiff가 설치돼 있으면
oasdiff changelog <base> <rev>로 초안 생성 후 다듬기
실행 절차
- 라우트/핸들러/스키마 파일 탐색 (
**/routes/**,**/api/**,**/controllers/**, 프레임워크별 패턴) - 기존 명세가 있으면 실제 코드와 대조 → 불일치 목록 먼저 보고 후 갱신
- 신규면 OpenAPI 3.1 골격 생성 → 리소스별 채움
docs/api/README.md에 구성도 + 플로우 다이어그램docs/docs.yaml매니페스트에docs/api/*항목 갱신 (covers: 라우트 경로 글롭)- 명세 검증:
npx @redocly/cli lint docs/api/openapi.yaml또는npx @stoplight/spectral-cli lint(설치돼 있을 때만, 없으면 스킵하고 docs-ci 설치 제안)
제약
docs/폴더만 수정. 소스 코드 수정 금지- 코드에 없는 엔드포인트를 명세에 넣지 않는다