API 예시 응답을 신뢰하게 만드는 세 가지 습관

예시 JSON은 읽기 쉽지만 현실과 다르면 바로 신뢰를 잃습니다. 첫째, 모든 예시에 스키마 버전과 생성 시각을 주석 혹은 별도 표로 붙입니다. 둘째, 민감 필드는 일관된 마스킹 규칙을 적용해 독자가 패턴을 학습하도록 합니다.

셋째 단락에서는 ‘happy path’만 반복하지 않도록 부분 실패 응답을 한 건 포함하라고 권합니다. 상태 코드와 본문 필드가 어떻게 대응되는지 표로 연결하면 고객 지원 문의가 줄어듭니다. 마지막으로 예시를 자동 검증하는 최소 단위 테스트 아이디어를 소개합니다.