백엔드
모두가 행복해지는 API 문서 통합과 자동화
두줄요약
REST API 문서를 수동 관리할 때의 한계를 줄이기 위해 OpenAPI와 Redoc, GitHub Actions를 활용한 자동화 방안을 소개했습니다. 여러 서비스와 리포지터리의 문서를 그룹화해 하나의 URL로 통합하는 흐름도 설명했습니다.
핵심 내용
- REST API 문서를 수동 관리할 때 발생하는 문서 폭증, URL 난립, 배포 지연 문제 정리
- OpenAPI, Redoc, GitHub Actions, GitHub Pages를 조합해 문서를 통합·자동화하는 구조 제안
- API 스펙을 그룹화해 목적별 문서를 분리하고, 여러 서비스 또는 여러 리포지터리의 문서를 하나의 페이지로 합치는 흐름 설명
- JSON 추출, Redocly join/bundle/build-docs, yq로 제목·설명 보강, HTML 배포까지의 자동화 절차 소개
적용해볼 점
- 스펙 변경만으로 문서가 갱신되도록 CI 기반 문서 파이프라인 구성
- 독자별 목적에 맞게 API 그룹을 나눠 혼재를 줄이는 방식 적용
- 문서 전용 리포지터리와 워크플로 호출 구조로 다중 리포지터리 문서 통합 확장