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