[NHN FORWARD 2020] MSA 환경에서 API 문서 관리하기: 생성부터 배포까지

초기 모노리틱 스프링 서비스에서 Swagger를 채택해 어노테이션 기반으로 문서를 만든 이유를 설명한다. 개발이 쉽고 현행화가 잘 되며 화면에서 직접 호출할 수 있는 장점과, 프로덕션 코드에 문서용 코드가 섞이고 로직 검증 없이 문서화되는 단점을 함께 짚는다.

MSA로 전환하면 서버마다 문서가 하나씩 붙어 흩어지고, 사용자가 모든 문서 주소를 알아야 하는 불편이 생긴다. 이를 Swagger UI로 해결해 서버 실행과 무관하게 OpenAPI 스펙 파일만 있으면 여러 문서를 한 곳에서 볼 수 있게 만든 과정을 소개한다.

Swagger는 속성이 추가돼도 검증 없이 문서화되는 약점이 있다. 이를 막기 위해 테스트가 성공해야 문서가 만들어지는 Spring REST Docs를 도입해, 테스트에 속성이 누락되면 문서가 생성되지 않도록 현행화를 강제한 이유를 설명한다.

Spring REST Docs로 검증 가능한 문서를 만들고 이를 Swagger UI로 통합하기 위해, 산출물을 OpenAPI 스펙으로 변환하는 오픈소스를 활용한다. 테스트 코드 작성 방식과 빌드 성공 시 생성되는 YAML 파일을 Swagger UI에 넣는 예제를 보여준다.

각 서비스 저장소에서 생성된 문서를 하나로 모으는 자동화를 다룬다. 빌드·배포에 Jenkins 파이프라인을 쓰고, 프로비저닝 툴 Ansible의 복사 기능으로 각 서버의 문서를 문서화 서버에 취합하는 구조를 설명한다.

개발자 push → 저장소 이벤트 → Jenkins 체크아웃·빌드 → 성공 시 Ansible 플레이북으로 문서 서버 복사로 이어지는 전체 플로우를 정리한다. 셀렉트 박스로 각 서버 API를 골라보는 실제 통합 문서 화면을 보여주며 협업 효율을 강조한다.