API Doc Standards — API 문서 작성 표준
doc-writer 에이전트의 API 문서 품질을 표준화하는 규격과 패턴.
REST API 문서 필수 섹션
1. 개요 — API 목적, 대상 사용자, 기본 URL
2. 인증 — 인증 방식, 토큰 획득/갱신
3. 공통 규격 — 요청/응답 포맷, 페이지네이션, 에러 코드
4. 엔드포인트 레퍼런스 — 리소스별 CRUD
5. 에러 처리 — 에러 코드 테이블, 트러블슈팅
6. 변경 이력 — 버전별 변경사항
엔드포인트 문서 템플릿
## POST /api/v1/users
사용자를 생성합니다.
### 요청
**헤더**
| 헤더 | 값 | 필수 |
|------|-----|------|
| Authorization | Bearer {token} | O |
| Content-Type | application/json | O |
**본문**
| 필드 | 타입 | 필수 | 설명 | 제약조건 |
|------|------|------|------|---------|
| email | string | O | 이메일 | RFC 5322, 254자 |
| name | string | O | 이름 | 2~50자 |
| role | string | X | 역할 | admin/user/viewer, 기본: user |
### 응답
**성공 (201 Created)**
{ "id": "usr_abc123", "email": "...", "name": "..." }
**에러**
| 상태 | 코드 | 설명 |
|------|------|------|
| 400 | INVALID_EMAIL | 이메일 형식 오류 |
| 409 | DUPLICATE_EMAIL | 중복 이메일 |
| 422 | VALIDATION_ERROR | 유효성 오류 |
에러 응답 표준 형식
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "요청한 리소스를 찾을 수 없습니다.",
"details": [{ "field": "user_id", "reason": "존재하지 않음" }],
"request_id": "req_xyz789"
}
}
HTTP 상태 코드 매핑
| 범위 |
의미 |
사용 코드 |
| 2xx |
성공 |
200, 201, 204 |
| 4xx |
클라이언트 에러 |
400, 401, 403, 404, 409, 422, 429 |
| 5xx |
서버 에러 |
500, 502, 503 |
페이지네이션 문서 표준
커서 기반 (권장)
| 파라미터 |
타입 |
기본값 |
설명 |
| limit |
integer |
20 |
항목 수 (1~100) |
| cursor |
string |
- |
다음 페이지 커서 |
응답 메타: has_more, next_cursor
오프셋 기반
| 파라미터 |
타입 |
기본값 |
설명 |
| page |
integer |
1 |
페이지 번호 |
| per_page |
integer |
20 |
항목 수 |
| sort |
string |
created_at |
정렬 기준 |
| order |
string |
desc |
정렬 방향 |
인증 섹션 표준
## 인증
모든 API 요청에 Bearer 토큰 필요.
### 토큰 획득: POST /auth/token
### 토큰 사용: Authorization: Bearer {access_token}
### 토큰 갱신: POST /auth/refresh (만료 시)
| 상태 코드 | 원인 | 조치 |
|----------|------|------|
| 401 | 토큰 누락/만료 | 재발급 |
| 403 | 권한 부족 | 역할 확인 |
Rate Limiting 문서 표준
| 플랜 |
제한 |
단위 |
| Free |
100 |
분당 |
| Pro |
1,000 |
분당 |
| Enterprise |
10,000 |
분당 |
응답 헤더: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
초과 시: 429 + Retry-After 헤더
버저닝 문서 표준
- URL 경로 버전:
/api/v1/, /api/v2/
- 하위 호환: 새 필드/엔드포인트/옵션 파라미터 추가
- 호환 불가: 필드 삭제, 구조 변경, 필수 파라미터 추가 → 새 버전 필요
- 폐기 예고: 최소 6개월 전
문서 품질 체크리스트
| 항목 |
기준 |
| 예시 |
모든 엔드포인트에 요청+응답+에러 |
| 타입 |
string, integer, boolean, array, object |
| 필수/선택 |
모든 파라미터에 표시 |
| 제약조건 |
길이, 허용 값, 패턴 |
| 인증 |
엔드포인트별 필요 권한 |
| SDK 예제 |
cURL + 1개 이상 언어 |
| 변경 이력 |
날짜 + 변경 + 영향 범위 |
1---2name: api-doc-standards-23description: API 문서 작성 표준 및 패턴 라이브러리. doc-writer 에이전트가 REST/GraphQL/gRPC API 문서를 작성할 때 참조하는 표준. 'API 문서 표준', 'API 레퍼런스 작성' 요청 시 사용. 단, OpenAPI Spec 자동 생성이나 API 테스트 실행은 범위 밖.4---56# API Doc Standards — API 문서 작성 표준78doc-writer 에이전트의 API 문서 품질을 표준화하는 규격과 패턴.910## REST API 문서 필수 섹션1112```131. 개요 — API 목적, 대상 사용자, 기본 URL142. 인증 — 인증 방식, 토큰 획득/갱신153. 공통 규격 — 요청/응답 포맷, 페이지네이션, 에러 코드164. 엔드포인트 레퍼런스 — 리소스별 CRUD175. 에러 처리 — 에러 코드 테이블, 트러블슈팅186. 변경 이력 — 버전별 변경사항19```2021## 엔드포인트 문서 템플릿2223```markdown24## POST /api/v1/users2526사용자를 생성합니다.2728### 요청2930**헤더**31| 헤더 | 값 | 필수 |32|------|-----|------|33| Authorization | Bearer {token} | O |34| Content-Type | application/json | O |3536**본문**37| 필드 | 타입 | 필수 | 설명 | 제약조건 |38|------|------|------|------|---------|39| email | string | O | 이메일 | RFC 5322, 254자 |40| name | string | O | 이름 | 2~50자 |41| role | string | X | 역할 | admin/user/viewer, 기본: user |4243### 응답4445**성공 (201 Created)**46{ "id": "usr_abc123", "email": "...", "name": "..." }4748**에러**49| 상태 | 코드 | 설명 |50|------|------|------|51| 400 | INVALID_EMAIL | 이메일 형식 오류 |52| 409 | DUPLICATE_EMAIL | 중복 이메일 |53| 422 | VALIDATION_ERROR | 유효성 오류 |54```5556## 에러 응답 표준 형식5758```json59{60 "error": {61 "code": "RESOURCE_NOT_FOUND",62 "message": "요청한 리소스를 찾을 수 없습니다.",63 "details": [{ "field": "user_id", "reason": "존재하지 않음" }],64 "request_id": "req_xyz789"65 }66}67```6869## HTTP 상태 코드 매핑7071| 범위 | 의미 | 사용 코드 |72|------|------|----------|73| 2xx | 성공 | 200, 201, 204 |74| 4xx | 클라이언트 에러 | 400, 401, 403, 404, 409, 422, 429 |75| 5xx | 서버 에러 | 500, 502, 503 |7677## 페이지네이션 문서 표준7879### 커서 기반 (권장)8081| 파라미터 | 타입 | 기본값 | 설명 |82|---------|------|-------|------|83| limit | integer | 20 | 항목 수 (1~100) |84| cursor | string | - | 다음 페이지 커서 |8586응답 메타: `has_more`, `next_cursor`8788### 오프셋 기반8990| 파라미터 | 타입 | 기본값 | 설명 |91|---------|------|-------|------|92| page | integer | 1 | 페이지 번호 |93| per_page | integer | 20 | 항목 수 |94| sort | string | created_at | 정렬 기준 |95| order | string | desc | 정렬 방향 |9697## 인증 섹션 표준9899```markdown100## 인증101모든 API 요청에 Bearer 토큰 필요.102103### 토큰 획득: POST /auth/token104### 토큰 사용: Authorization: Bearer {access_token}105### 토큰 갱신: POST /auth/refresh (만료 시)106107| 상태 코드 | 원인 | 조치 |108|----------|------|------|109| 401 | 토큰 누락/만료 | 재발급 |110| 403 | 권한 부족 | 역할 확인 |111```112113## Rate Limiting 문서 표준114115| 플랜 | 제한 | 단위 |116|------|------|------|117| Free | 100 | 분당 |118| Pro | 1,000 | 분당 |119| Enterprise | 10,000 | 분당 |120121응답 헤더: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`122초과 시: 429 + `Retry-After` 헤더123124## 버저닝 문서 표준125126- URL 경로 버전: `/api/v1/`, `/api/v2/`127- 하위 호환: 새 필드/엔드포인트/옵션 파라미터 추가128- 호환 불가: 필드 삭제, 구조 변경, 필수 파라미터 추가 → 새 버전 필요129- 폐기 예고: 최소 6개월 전130131## 문서 품질 체크리스트132133| 항목 | 기준 |134|------|------|135| 예시 | 모든 엔드포인트에 요청+응답+에러 |136| 타입 | string, integer, boolean, array, object |137| 필수/선택 | 모든 파라미터에 표시 |138| 제약조건 | 길이, 허용 값, 패턴 |139| 인증 | 엔드포인트별 필요 권한 |140| SDK 예제 | cURL + 1개 이상 언어 |141| 변경 이력 | 날짜 + 변경 + 영향 범위 |