API 개발을 진행하다 보면 다양한 설계서, 명세서, 테스트 문서 등이 쌓이게 됩니다. 이를 체계적으로 관리하기 위해 가장 기본이자 중요한 것이 바로 문서 번호 체계입니다.
이번 포스팅에서는 API 설계서 번호 포맷을 어떻게 구성하면 좋을지 실무 경험과 예시를 바탕으로 정리해보았습니다.
왜 문서 번호 포맷이 중요한가요?
- 문서가 많아질수록 검색이 쉬워지고
- 팀원들과 협업이 명확해지며
- 변경 이력 관리나 리뷰 시 추적이 용이합니다.
추천 포맷 구조
[시스템명]-API-[버전]-[문서유형]-[일련번호]
구성 요소 설명
| 구성 요소 | 설명 | 예시 |
| 시스템명 (Domain) | 해당 API가 속한 주요 도메인 명칭 | USER, ORDER, PAY, ADMIN 등 |
| API | API 문서임을 명시 | API |
| 버전 | API 버전 | V1, V2 등 |
| 문서유형 | 문서 종류 | SPEC (설계서), DOC (설명서), TEST (테스트케이스) 등 |
| 일련번호 | 001부터 시작하여 고유 번호 지정 | 001, 002, 003 등 |
기본 예시
1. 사용자 도메인의 회원가입 API
USER-API-V1-SPEC-001
- 도메인: USER
- 문서 유형: API 설계서
- 버전: V1
- 일련번호: 001
문서 제목 예시: 001. 회원가입 API 설계서 (USER-API-V1-SPEC-001)
2. 주문 도메인의 주문 생성 API
ORDER-API-V1-SPEC-002
문서 제목 예시: 002. 주문 생성 API 설계서 (ORDER-API-V1-SPEC-002)
3. 결제 도메인의 결제 확인 API
PAY-API-V1-SPEC-003
확장된 포맷 예시
날짜 포함형
문서 생성일자까지 관리할 경우:
USER-API-V1-SPEC-20250330-001
생성일자: 2025년 3월 30일
팀 구분 포함형
FE/BE 팀별 문서 구분 시:
FEED-API-V1-SPEC-FE-001
FEED-API-V1-SPEC-BE-002
API Endpoint 포함형
문서 내 API 경로를 명시하면 가독성 향상:
USER-API-V1-SPEC-004 (/users/signup)
실전 활용 팁
문서 제목 네이밍
Notion, Confluence, Wiki에서 문서 제목을 아래와 같이 지정하면 검색이 쉽고 체계적으로 관리됩니다:
005. 비밀번호 재설정 API 설계서 (USER-API-V1-SPEC-005)
일괄 관리용 문서 번호 자동화
문서가 많아지면 Excel에서 아래와 같이 관리해보세요:
| No. | 문서 제목 | 문서 번호 | 버전 | 작성일 |
| 1 | 회원가입 API | USER-API-V1-SPEC-001 | V1 | 2025-03-30 |
| 2 | 주문 생성 API | ORDER-API-V1-SPEC-002 | V1 | 2025-03-30 |
| 3 | 결제 확인 API | PAY-API-V1-SPEC-003 | V1 | 2025-03-30 |
마무리하며
문서화는 단순한 문서 작성을 넘어서 협업의 기본이자 품질 관리의 핵심입니다. 문서 번호 체계를 잘 잡아두면 팀원 간 커뮤니케이션이 쉬워지고, 유지보수 또한 훨씬 수월해집니다.
여러분만의 팀이나 프로젝트에 맞게 약간씩 커스터마이징해서 적용해보세요!
댓글