API 문서 최신화: 코드 변경 후 확인할 6가지

API 문서 최신화는 변경된 스키마를 반영하는 데서 끝나지 않습니다. 호출하는 사람이 무엇을 보내고 어떤 결과를 받는지, 기존 사용법이 계속 유효한지까지 설명을 맞추는 작업입니다.

코드 변경 후 확인할 6가지

1. 요청: 필수·선택 파라미터와 기본값이 바뀌었는지 확인합니다.
2. 응답: 필드 이름, 타입, null 허용 여부를 확인합니다.
3. 인증: 헤더, 권한, 토큰 요구사항을 확인합니다.
4. 오류: 상태 코드와 오류 응답의 처리 방법을 확인합니다.
5. 예시: 복사한 요청과 코드 예제가 실제로 동작하는지 실행합니다.
6. 호환성: 기존 호출자에게 영향이 있는지와 전환 안내가 필요한지 확인합니다.

필드 이름이 바뀌는 예시

status를 payment_status로 바꾸는 상황을 가정합니다. 이름만 치환하면 상태값의 의미나 기존 호출자의 처리 방식이 누락될 수 있습니다. 변경 커밋과 테스트를 확인하고, 이전 이름을 언제까지 지원하는지 팀의 결정도 기록하세요. 이 예시는 설명용이며 실제 성과 수치나 고객 사례가 아닙니다.

OpenAPI와 설명 문서의 역할

OpenAPI는 HTTP API의 인터페이스를 기술하는 표준입니다. 스키마를 관리하더라도 인증 설정 이유, 재시도 판단, 마이그레이션 안내 같은 설명은 함께 검토해야 합니다. OpenAPI 공식 명세를 기준으로 인터페이스와 팀의 설명 문서를 구분해 관리하세요. 이 가이드는 Specify가 모든 OpenAPI 도구와 자동 연동된다는 뜻은 아닙니다.

Specify에서 수정안 확인하기

GitHub와 문서 프로젝트의 소스를 연결하고 관련 API 문서를 생성·관리합니다. 변경안에서 수정 전후와 근거를 확인하고 실제 인터페이스와 대조하세요. 반영 범위는 프로젝트 설정과 적용 정책에 따릅니다. 상세 연결 순서는 GitHub 문서 연동 가이드를 참고하세요.

팀이 남길 검토 기록

변경 커밋, 영향받는 엔드포인트, 바뀐 요청·응답, 검증한 예시, 호환성 판단, 검토 담당자를 기록하면 다음 변경에서도 같은 기준으로 확인할 수 있습니다. 자동화가 검토할 대상을 준비하고, 팀은 실제 사용 계약을 확인하는 방식으로 시작하세요.

개발문서 자동화 기능 · 워크스페이스 시작 · 온보딩 문서 생성