마이크로 서비스 환경에서 통합된 API 문서 서버 구축하기

문제 상황

• 마이크로 서비스 환경에서 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로 제공해 사용 편의성 향상