Swagger와 REST Docs를 같이 가져가는 이유

내부 개발망에서 Swagger와 Spring REST Docs를 설정하면서 예상보다 오랜 시간을 보낸 적이 있습니다.

처음에는 Swagger 화면을 열고 REST Docs 문서가 생성되게 하면 끝나는 작업이라고 생각했습니다. 하지만 라이브러리 반입 여부부터 Gradle Task, 테스트와 문서 생성 경로까지 하나씩 맞춰야 했습니다.

설정을 들여다볼수록 두 도구를 같이 사용하는 이유도 더 분명해졌습니다.

Swagger는 개발 중의 대화에 가까웠습니다

Swagger는 API 목록과 요청·응답 구조를 바로 확인하고 직접 호출해볼 수 있습니다.

프론트엔드 개발자는 아직 화면에 연결하지 않은 API도 브라우저에서 확인할 수 있고, 백엔드 개발자는 인증 헤더와 요청 값이 예상대로 처리되는지 빠르게 점검할 수 있습니다.

하지만 화면을 띄우는 것만으로는 충분하지 않았습니다. API를 업무 기준으로 분류하고, 공통 인증 헤더와 서버 주소를 맞추며, 요청과 응답의 설명을 같은 방식으로 작성해야 했습니다.

기준이 없으면 Swagger가 있어도 API마다 표현 방식이 달라집니다. 개발자가 빠르게 확인할 수 있다는 장점은 문서화 규칙이 함께 있을 때 더 잘 작동했습니다.

Spring REST Docs는 테스트 결과를 기반으로 문서 조각을 생성합니다. 작성한 테스트가 성공해야 요청과 응답 예시, 필드 설명이 문서에 포함됩니다.

Swagger가 개발 중 빠르게 확인하고 대화하기 위한 도구라면 REST Docs는 테스트로 확인한 API 계약을 남기는 도구에 가까웠습니다.

물론 테스트 코드와 문서 작성 비용이 생깁니다. 모든 API를 처음부터 상세하게 문서화하면 부담이 커질 수도 있습니다.

이번 프로젝트에서는 운영에 필요한 주요 업무와 공통 API부터 REST Docs로 남기고, 개발 중 확인은 Swagger를 활용하는 방향을 선택했습니다. 도구를 하나로 통일하기보다 사용하는 시점과 목적을 구분했습니다.

두 도구를 함께 사용하면 문서가 두 벌이 되는 문제가 생길 수 있습니다.

Swagger에는 새로운 필드가 있는데 REST Docs에는 없거나, 테스트 문서는 통과했지만 실제 개발 서버의 설정이 다른 상황도 발생할 수 있습니다. 도구를 추가하는 것보다 변경 흐름을 함께 관리하는 일이 중요했습니다.

API 변경 시 구현 코드와 테스트, Swagger 설명을 같은 작업에서 수정하도록 했습니다. 공통 응답과 예외 구조도 프로젝트 기준으로 먼저 맞췄습니다.

CI 과정에서는 테스트와 REST Docs 생성을 함께 수행하고, Swagger는 실제 개발 환경에서 호출 가능한 주소와 인증 방식을 제공하도록 역할을 나눴습니다.

Swagger와 REST Docs 설정은 눈에 보이는 기능을 만드는 작업은 아니었습니다. 하지만 이후 여러 개발자가 같은 방식으로 API를 만들고 확인할 수 있는 기반이 되었습니다.

API 문서는 완성된 결과를 나중에 정리하는 산출물만은 아니었습니다. 개발 중에는 서로의 이해를 맞추고, 변경 시에는 무엇이 달라졌는지 확인하며, 테스트에서는 약속이 지켜졌는지를 검증하는 기준이었습니다.

두 도구를 함께 가져간 이유는 더 많은 문서를 만들기 위해서가 아닙니다. 빠르게 확인해야 하는 순간과 검증된 기록이 필요한 순간이 서로 달랐기 때문입니다.