코드에서 다시 계산하는 API 연동 현황

배경: 팀이 공유하는 API 현황의 기준

심케어 3.0은 관리자·상담사·내담자 웹에서 각각 API를 연결하는 프로젝트입니다. PM과 개발자가 같은 구현 현황을 확인할 수 있도록 API 상태 파일과 Confluence 문서를 관리했습니다.

이때 필요한 정보는 단순한 진행률이 아니었습니다. 어떤 호출이 구현돼 있고, 실제 화면에서 사용되는지, 서버와 통신하는 QA까지 끝났는지를 구분해야 다음 작업을 결정할 수 있었습니다.

문제: 문서 게시 성공이 최신 상태를 뜻하지 않았다

첫 자동화는 PR의 변경을 확인한 bot이 상태 파일을 수정하는 방식이었습니다. 그러나 당시 runner에 없는 GitHub CLI에 의존해 갱신이 반복 실패했고, 게시 단계는 바뀌지 않은 JSON을 다시 문서로 옮겼습니다.

표가 다시 게시됐다는 사실만 보면 최신화된 것처럼 보일 수 있었습니다. 실제로는 상태를 계산하는 단계와 문서를 게시하는 단계 사이에 오래된 파일이 남아 있었습니다.

호출 탐지도 단순하지 않았습니다. 상수·template literal·helper를 거친 호출을 충분히 감지하지 못했고, 기존 상태 행이 수동 지정으로 취급돼 구현이 있어도 미착수로 남는 경우가 설계 기록에 있습니다.

판단: 계산할 정보와 사람이 기록할 정보를 분리

현재 소스 전체와 커밋된 OpenAPI에서 연동 상태를 다시 계산하도록 바꿨습니다. 코드에서 구할 수 있는 결과를 상태 파일에 계속 써 넣는 의존성을 줄이고, 사람이 판단해야 하는 정보만 별도로 남겼습니다.

상태 파일의 갱신 여부에 기대는 대신, 보고할 때마다 같은 커밋의 소스와 명세에서 상태를 계산하도록 했습니다.

구조: 명세에서 호출, 화면 연결, 보고서까지

관리자·상담사·내담자 앱을 분석해 API 호출의 method와 path를 명세에 대조했습니다. 호출 함수가 있다는 것에서 멈추지 않고 화면의 import 관계까지 확인했습니다.

테스트 파일의 호출은 제품 구현 근거에서 제외했습니다. 정적으로 해석하지 못한 호출과 계약에 등록되지 않은 호출은 별도의 검사 대상으로 드러내도록 했습니다.

핵심 구현 1: 무엇을 ‘연동 완료’라고 부를 것인가

코드 연결, endpoint 테스트, 실제 API QA는 서로 다른 근거입니다. 분석 도구가 이해할 수 있는 범위를 완료 기준에 명시해야, 읽는 사람이 코드상 연결을 운영 검증으로 받아들이지 않습니다.

핵심 구현 2: 검증한 커밋과 게시한 커밋 맞추기

develop의 CI가 성공하면 해당 실행의 head SHA를 checkout해서 분석·게시하도록 구성했습니다. 이 연결이 없으면 CI는 A 커밋을 검증했는데 문서는 이후 B 커밋을 분석하는 식으로 기준이 달라질 수 있습니다.

Confluence 전체 문서를 덮어쓰지 않고 자동 관리 영역만 교체하며 기준 커밋과 동기화 시각을 표시합니다. 같은 분석 결과를 PR 보고서에도 전달해 검토자가 변경을 확인하는 위치에서 볼 수 있게 했습니다.

결과: 코드 연동과 실제 API QA를 따로 보여주기

보고서에는 코드에서 찾은 연결과 사람이 확인한 실제 API QA를 따로 표시합니다. 로컬 dry-run까지 확인했으며, 문서의 실제 게시와 운영 API 응답은 별도의 검증 단계로 둡니다.

원본 보기 ↗

돌아보며: 파생 상태의 원본을 어디에 둘 것인가

이 변경에서 제가 사용한 기준은 ‘코드로 다시 계산할 수 있는 상태인가, 사람이 별도로 기록해야 하는 판단인가’였습니다. 전자는 기준 커밋에서 산출하고 후자는 예외·메모·QA로 남기는 구분이 구현과 보고에 함께 적용됐습니다.

다음에는 팀이 이전 상태표와 새 보고서를 보며 어떤 판단을 다르게 하는지 확인하고 싶습니다.