백엔드
더 자유롭고, 빠르고, 정확하게: 토스페이먼츠 API 문서 엔지니어링
두줄요약
토스페이먼츠가 MDX와 OAS, remark를 결합해 API 문서 작성의 자유도와 정확도를 높인 사례를 소개했습니다. 스펙 자동화와 PR 기반 반영으로 반복 작업을 줄이고 문서 품질을 개선했습니다.
핵심 내용
- 토스페이먼츠 API 문서 엔지니어링에 MDX, OAS, remark를 결합해 문서 작성 자유도와 자동화를 높인 사례
- MDX로 React 컴포넌트를 삽입해 문서 구조와 UI를 유연하게 구성
- OAS 스펙과 GitHub Actions로 API 변경 사항을 문서 레포지토리에 자동 반영
- remark 플러그인으로 MDX의 리스트 기반 파라미터 설명을 스키마 컴포넌트로 변환해 정확도 향상
적용해볼 점
- 반복적인 API 문서 수작업을 스펙 기반 자동화로 전환
- 문서 작성자와 개발자 간 스펙 전달 과정을 PR 흐름으로 단순화
- 파라미터 이름과 설명만 작성해도 나머지 메타정보를 자동 채우는 구조 설계
