API 문서를 엑셀이나 PDF로 작성하고 메일로 공유하는 방식은 너무 익숙합니다.
문제가 발생하면 담당자에게 연락하고, 과거 메일을 찾아 고객사가 가진 문서의 버전을 확인합니다. 변경된 내용을 다시 설명하고 수정된 문서를 보낸 뒤, 제대로 반영됐는지 또 확인합니다.
우리는 이 과정을 너무 많이 반복한 나머지 원래 필요한 업무라고 생각하게 되었습니다.
하지만 문제는 한 번의 잘못된 문서에서 끝나지 않습니다.
API가 변경될 때마다 새로운 파일과 메일, 고객사별 예외와 담당자의 기억이 하나씩 쌓입니다. 처음에는 작은 불편이지만 시간이 지날수록 어떤 문서가 기준인지 확인하기 어려워지고, 문제를 해결하는 데 필요한 사람과 시간도 함께 늘어납니다.
고객사가 이전 버전의 요청 형식으로 개발하면 연동 오류와 재작업이 발생합니다. 필수 항목이나 인증 방식이 다르게 전달되면 개발 일정이 지연되고, 이미 운영 중인 API라면 데이터 오류나 장애로 이어질 수도 있습니다.
문제가 발생한 뒤에야 내부 개발팀과 고객사가 서로 다른 문서를 보고 있었다는 사실을 발견합니다.
그때부터 개발자는 진행하던 작업을 멈추고 원인을 확인합니다. 운영 담당자는 과거 문서와 전달 이력을 찾고, 고객사는 자신의 구현과 전달받은 명세를 다시 검증합니다. 하나의 문서 불일치가 여러 사람의 업무를 동시에 멈추게 합니다.
그런데도 대부분의 문제는 전화와 메일, 메신저로 조용히 해결됩니다.
누군가는 수정된 파일을 다시 보내고, 누군가는 고객사에 상황을 설명하고, 개발자는 급하게 예외 처리를 추가합니다. 당장의 문제는 해결되지만 왜 발생했는지, 어떤 고객사가 영향을 받았는지, 같은 문제가 반복되지 않게 무엇을 바꿨는지는 조직에 남지 않습니다.
이 과정에 사용되는 시간은 원래 개발과 제품 개선에 사용됐어야 할 시간입니다.
더 큰 문제는 이 모든 과정이 특정 담당자의 경험과 기억, 메일함에 의존한다는 것입니다. 담당자가 자리를 비우거나 퇴사하면 조직은 메일과 메신저 기록을 뒤지며 업무를 다시 복원해야 합니다.
관리되지 않은 API 문서는 사라지지 않습니다. 조직 안팎에 계속 남아 보이지 않는 문서 부채가 됩니다.
우리는 문제를 해결하고 있는 것이 아니라, 문제가 발생할 때마다 사람의 시간으로 막아내는 방식에 익숙해진 것일지도 모릅니다.
이러한 문제를 실제 업무에서 겪은 저는 스펙브릿지를 만들었습니다.
스펙브릿지는 단순히 API 문서를 작성하는 도구가 아닙니다. 문서의 변경사항을 검토하고, 승인된 버전만 고객사와 외부 파트너에게 배포하는 API 문서 운영 도구입니다.
기존 Swagger를 대체하는 것이 아니라 Swagger/OpenAPI와 Postman Collection을 가져온 뒤, 외부 전달 과정에서 발생하는 문제를 관리하는 데 집중했습니다.
- 현재 배포본과 수정본의 차이 비교
- 변경사항 검토와 승인
- 초안과 고객사가 보는 배포본 분리
- 고객사별 문서 공개 범위 관리
- 공개 링크 비밀번호와 만료일 설정
- 같은 링크에서 승인된 최신 문서 제공
고객사에 매번 새로운 파일을 보낼 필요 없이, 내부 검토가 끝난 문서만 기존 링크에 다시 배포할 수 있습니다.
개발자는 문서를 찾고 다시 전달하는 반복 업무를 줄이고, 조직은 특정 담당자의 기억이 아닌 기록된 변경 이력과 배포 기준으로 API 문서를 관리할 수 있습니다.
현재 스펙브릿지를 실제 API 문서 운영에 사용하고 솔직한 피드백을 주실 파트너를 찾고 있습니다.
엑셀이나 PDF로 API 문서를 관리하거나, API가 변경될 때마다 고객사에 문서를 다시 전달하고 있는 팀이라면 현재 사용 중인 문서 한 개부터 함께 검증해 보고 싶습니다.
잘 만들어진 기능에 대한 칭찬보다 실제 운영에서 불편한 부분, 불필요한 절차, 빠진 기능에 대한 솔직한 의견을 듣고 싶습니다.