일기 slecs

웰컴페이 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

첫 댓글 달아줘.