더 자유롭고, 빠르고, 정확하게: 토스페이먼츠 API 문서 엔지니어링

API 스펙 변경을 문서에 옮기는 반복 작업과 정보 불일치 문제를 줄이기 위해 토스페이먼츠는 MDX, OAS, remark를 결합한 문서 엔지니어링 시스템을 구축했다. MDX로 React 컴포넌트를 삽입해 문서를 자유롭게 구성하고, 서버 코드 변경 시 GitHub Actions가 OAS 스키마 업데이트 PR을 문서 저장소에 자동 생성하도록 했다. remark 플러그인은 MDX의 파라미터 목록을 AST에서 컴포넌트 노드로 바꾸고 OAS의 타입·필수 여부 등을 연결해 반복 정보를 자동으로 렌더링한다. API 스펙은 엔지니어가 OAS에서 관리하되 설명은 테크니컬 라이터가 MDX에서 관리해, 정확성을 높이면서 문서 수정의 속도와 자율성을 확보했다.

• MDX에서는 Markdown과 React 컴포넌트를 함께 사용해 문서 레이아웃과 상호작용 요소를 유연하게 구성할 수 있다.
• OAS를 서버 API의 기준 명세로 두고 GitHub Actions로 문서 저장소에 스키마 업데이트 PR을 생성하면 변경사항 전달과 검토를 간소화할 수 있다.
• remark 플러그인으로 Markdown AST를 변환해 OAS의 타입·필수 여부 같은 정보를 문서 컴포넌트에 연결할 수 있다.
• API 스펙과 설명 콘텐츠의 관리 주체를 구분하면 자동화의 이점을 살리면서도 테크니컬 라이터가 문서 내용을 빠르게 조정할 수 있다.