백엔드
마이크로 서비스 환경에서 통합된 API 문서 서버 구축하기
두줄요약
마이크로 서비스 환경에서 흩어진 API 문서를 OpenAPI로 통일해 공용 문서 서버를 구축했습니다. GitHub Action과 S3로 배포마다 문서를 자동 갱신해 관리 부담을 줄였습니다.
문제 상황
- 마이크로 서비스 환경에서 Swagger, Spring Rest Docs, 노션 등 서로 다른 방식으로 API 문서를 관리하는 혼재 상태
- 도메인별로 분산된 문서를 공유할 때 URL을 하나씩 전달해야 하는 비효율과 커뮤니케이션 혼선
해결 방법
- Swagger와 Spring Rest Docs 문서를 OpenAPI 형식으로 통일해 공용 API 문서 서버로 집약
- restdocs-api-spec과 Gradle openapi3 명령으로 Spring Rest Docs 테스트 코드에서 OpenAPI 문서 생성
- Swagger UI로 복수 OpenAPI 문서를 한 화면에서 조회하고, GitHub Action과 S3 업로드로 배포 시 자동 갱신
성능/운영 포인트
- 개발 환경 배포 시점마다 문서를 자동 생성·업로드해 수작업 재배포 부담 제거
- 운영 환경이 아닌 개발 환경에만 문서 서버를 두어 상용 데이터 변경 위험 최소화
- API 테스트 기능과 문서 조회를 하나의 UI로 제공해 사용 편의성 향상
