이커머스 결제 API 문서 전면 보완으로 코드 불일치까지 해결

이커머스 결제 연동 플랫폼 API 명세 전체 보완 및 신규 섹션 추가

2026-02-06. API 문서 작업. 코드가 아무리 잘 짜여 있어도 문서가 없으면 다른 사람이, 또는 미래의 내가 쓰기 어려움.

문서화 범위

• API 엔드포인트: 경로, HTTP 메서드, 요청/응답 스펙
• 파라미터 명세: 필수/선택 여부, 타입, 유효성 규칙
• 오류 코드: 상황별 에러 코드 및 메시지
• 사용 예시: 실제 동작하는 요청/응답 샘플

## GET /api/v1/users/{id}

### Request
- id (required): 사용자 식별자

### Response (200 OK)
{ "id": 1, "name": "홍길동", "status": "ACTIVE" }

### Errors
- 400: 파라미터 오류
- 401: 인증 필요
- 404: 리소스 없음

문서 작성하면서 코드와 실제 동작이 다른 부분 몇 군데 발견해서 같이 수정했음. 이게 문서화의 부수 효과 중 하나임. 코드를 다시 한 번 검토하게 되고, 그 과정에서 누락이나 불일치를 발견하게 됨.

문서화를 하면서 느낀 것

코드를 짤 때는 '나는 알고 있으니까 괜찮다'고 생각하기 쉬움. 그런데 6개월 뒤에 같은 코드를 보면 낯설어지는 경험을 한 번쯤 해봤을 거임.

문서화의 핵심은 '왜'를 기록하는 것임. '무엇'은 코드를 보면 알 수 있지만, '왜 이렇게 설계했는가'는 코드에서 드러나지 않음. 이 부분이 빠지면 나중에 변경할 때 잘못된 방향으로 가기 쉬움.

앞으로 API나 복잡한 로직을 새로 만들 때마다 최소한 의사결정 배경은 남기려고 함.

다음