API Doc Writer Skill

목적

• •도메인 단위로 API 목록 문서(md)를 작성한다.
• •사용자가 놓치기 쉬운 정책/엣지 케이스를 질문 또는 제안으로 보강한다.
• •산출물은 문서 텍스트(마크다운)이며, 테스트 코드/구현 코드는 생성하지 않는다.

산출물 위치 운영 규칙(권장)

• •문서 폴더: docs/api/
• •도메인 문서 파일: docs/api/{domain}.md (예: article.md)
• •공통 컨벤션 문서: docs/api/_README.md

작업 모드

1) Domain Init (도메인 문서 골격 생성)

입력:

• •도메인명(예: Article)
• •도메인 설명(선택)
• •CRUD 필요 여부(기본: CRUD 생성)

출력:

• •templates/domain-doc.md 형식의 도메인 문서 골격
• •CRUD 엔드포인트 섹션 뼈대(요청/응답/정책/테스트/curl)

2) Endpoint Add/Update (엔드포인트 추가/수정)

입력:

• •도메인명
• •엔드포인트 제목
• •메서드/경로
• •인증/권한(필요 시)
• •요청 바디 DTO/필드/제약(필요 시)
• •성공 응답(상태코드, 헤더, 바디)
• •정책(정렬/페이징/유일성/소유권 은닉 등)

출력:

• •templates/endpoint.md 포맷의 엔드포인트 섹션
• •templates/tests.md 기준의 테스트 체크리스트
• •"추가 제안" 섹션(사람이 놓치기 쉬운 테스트/정책) 포함

3) Review (문서 품질 보강 제안)

입력:

• •도메인 문서 내용(또는 해당 엔드포인트 섹션)
• •현재 확정된 정책/컨벤션

출력:

• •누락된 정책/테스트 시나리오 목록
• •확정 항목과 합의 필요 항목을 분리

결정 질문(최소 질문 원칙)

다음 항목이 문서/테스트에 큰 영향을 주면 짧게 질문한다.

• •인증 필요 여부, 역할 제한 여부(401/403)
• •리소스 소유권이 있는지, 타인 리소스 접근을 404로 숨길지(404 은닉)
• •생성 API의 성공 응답(201+Location vs 204)
• •목록/탐색의 정렬 키/페이지 크기/continuationToken 규칙
• •중복(유일성) 위반의 처리 상태코드(기본: 400)

상태코드/정책 기본값

• •rules/status-codes.md, rules/auth.md, rules/validation.md, rules/paging-sorting.md를 따른다.
• •사용자가 별도 컨벤션을 지정하면 해당 컨벤션을 우선한다.

출력 텍스트 규칙

• •엔드포인트 섹션은 예시 포맷을 유지한다.
• •테스트 체크리스트는 기본적으로 [ ] 로 생성한다(문서 확정 후 사용자가 [x]로 변경).
• •curl 예시는 localhost:8080 기준으로 작성한다.