스웨거와 REST Docs, API 문서화 도구를 상황별로 고르는 법

출처 및 AI 안내: 이 글은 제미니의 개발실무 유튜브를 기반으로 작성되었습니다. gpt-5.6-sol 모델을 사용해 생성·편집했습니다.

스웨거에서는 클라이언트가 API를 살펴보고 곧바로 요청을 시도할 수 있다. Spring REST Docs는 요청과 응답 스니펫을 게시하기 전에 컨트롤러 계약을 실행하게 만든다. 신규 작업이라면 두 번째 교환을 선호하지만, 문서 없는 엔드포인트가 많은 인수 서비스에서는 스웨거가 현실적인 첫 수가 될 수 있다.

두 도구는 문서화 비용을 서로 다른 곳에 둔다

쓸 만한 스웨거 화면에는 자동 생성된 요청·응답 모양만으로 부족하다. 필드 조건, 인증 방식, 태그와 설정을 메인 소스셋과 컨트롤러 코드에 추가해야 한다. 대화형 UI는 편리하지만 문서 관심사가 실제 서비스 코드에 퍼지는 비용이 따른다.

REST Docs는 문서의 재료를 테스트에서 만든다. 서비스 계층이 충분히 검증돼 있다면 모킹하고 프레젠테이션 계층에 집중할 수 있다. 안쪽 계층까지 확인해야 한다면 더 넓은 통합 경로를 실행할 수도 있다. 어느 쪽이든 문서를 만들면서 요청 필드, 검증, 응답 필드처럼 자주 놓치는 컨트롤러 계약을 확인한다.

대신 기본 상태에서는 스웨거처럼 화면에서 바로 호출하기 어렵다. 클라이언트가 curl이나 별도 API 도구를 쓸 수 있다. 그 대가로 스니펫을 메인 소스셋 밖의 AsciiDoc에 조합하고 개발 환경 주소, 사전 조건, 팀 요청 사항, API 호출 뒤의 이벤트까지 자유롭게 설명할 수 있다.

응답 필드 하나가 바뀌면 차이가 드러난다

동료가 응답 필드를 추가하고 문서를 고치지 않았다고 하자. 스웨거는 새 모양을 자동으로 반영할 수 있다. REST Docs에서는 실제 응답에 있지만 명세에는 없는 필드 때문에 문서 테스트가 실패할 수 있다. 코드와 설명의 차이가 조용히 쌓이지 않고 실행 가능한 검증에서 드러난다.

내가 REST Docs를 계속 고르는 가장 큰 이유가 이 실패다. 코드를 보고 문서를 자동 생성하는 데서 끝나지 않고, 게시할 계약을 테스트 실행 중에 확인한다. AsciiDoc은 HTTP 스키마에 담기 어려운 맥락을 덧붙이고 도메인이나 API 묶음별로 문서를 나눌 여지도 준다.

문서 없는 레거시 API에서는 답이 달라진다

인수한 서비스에 엔드포인트가 많고 문서와 테스트가 거의 없다면 전체를 한 번에 REST Docs로 바꾸려는 계획부터 멈출 수 있다. 문서화가 끝나지 않는 또 하나의 개편이 되는 셈이다.

기존 API는 먼저 스웨거로 드러내고, 신규 API에는 REST Docs를 적용하며, 오래된 버전은 팀이 동작을 이해하고 테스트할 때마다 옮긴다. 이전 버전은 스웨거로 보이게 두고 새 버전부터 테스트된 문서로 시작할 수도 있다. 한 도구를 승자로 정하는 것이 목적이 아니다. 지금 시스템을 당장 쓸 수 있게 하면서 팀이 통제할 수 있는 새 작업의 계약 수준을 포기하지 않는 것이 중요하다.