웰컴페이 API 레퍼런스 문서 체계 정비
목차
docs: 웰컴페이 API 서비스 명세서 V1.6 추가
문서화 작업은 귀찮지만 나중을 위해 꼭 필요함. 특히 외부 API 연동 부분은 레퍼런스 없으면 매번 명세서 다시 뒤져야 함.
문서 구조
.claude/docs/
├── api-reference.md # 외부 API 엔드포인트 정리
├── architecture.md # 시스템 구조도
├── java.md # 코딩 컨벤션
├── sql.md # SQL 패턴/규칙
└── rbac.md # 권한 체계
좋은 API 레퍼런스 문서 요소
| 항목 | 내용 |
|---|---|
| 엔드포인트 | URL, Method, 인증 방식 |
| 요청 파라미터 | 타입, 필수 여부, 예시 |
| 응답 형식 | 성공/실패 각 샘플 |
| 에러 코드 | 코드 + 원인 + 대응 방법 |
문서 관리 원칙
코드 변경 시 관련 문서도 같이 업데이트해야 함. 코드와 문서가 따로 노는 순간부터 문서는 신뢰할 수 없게 됨.
개발 원칙 정리
이 작업을 진행하면서 재확인한 원칙들:
작은 커밋: 변경 단위를 작게 유지해서 코드 리뷰와 롤백이 쉽게.
테스트 먼저: 변경 전 현재 동작을 파악하고, 변경 후 동일하게 동작하는지 확인.
문서 동기화: 코드가 바뀌면 관련 주석과 문서도 같이 업데이트.
| 원칙 | 이유 |
|---|---|
| 단일 책임 | 하나의 함수/클래스는 하나의 역할만 |
| 명시적 코드 | 영리한 코드보다 읽기 쉬운 코드 |
| 실패 우선 처리 | happy path보다 에러 케이스 먼저 설계 |
끝
댓글 0
첫 댓글 달아줘.