Swagger와 RestDocs 비교: 장단점

API 명세서를 작성하기위해 Swagger와 RestDocs 를 고민하는중 우리는 Swagger를 선택하기로 했다. 그 이유를 작성하고자 한다.

Swagger란?

Swagger는 API 명세서를 코드를 작성하지 않고도 UI 형태로 생성할 수 있는 도구다.
덕분에 백엔드 개발자는 빠르게 API 문서를 만들고, 프론트엔드 개발자에게 공유할 수 있다.
또한, Swagger UI를 통해 API를 직접 테스트할 수도 있어, 개발 과정에서 매우 유용하다

RestDocs란?

Spring RestDocs는 API 문서를 테스트 코드 기반으로 작성하는 방식이다.
즉, 실제 동작하는 API를 테스트하며 문서를 생성할 수 있기 때문에,
Swagger보다 더 신뢰할 수 있는 문서를 만들 수 있는 장점이 있다.

하지만 RestDocs를 사용하려면 테스트 코드를 작성해야 하는 부담이 있다.
물론 테스트 코드를 작성하지 않고 문서를 생성하는 방법도 존재하지만,
이는 RestDocs의 장점을 충분히 살리지 못할 가능성이 크다.

우리는 왜 Swagger를 선택했을까?

우리는 다음과 같은 이유로 Swagger를 선택했다.

1. 빠른 문서 작성 → API 명세를 쉽게 자동 생성할 수 있다.
2. UI 기반의 문서 제공 → 프론트엔드 개발자가 쉽게 확인하고 테스트할 수 있다.
3. 테스트 코드 부담 없음 → RestDocs처럼 테스트 코드를 강제할 필요가 없다.

결과적으로, 우리는 API 명세서의 직관성과 빠른 공유를 중요하게 생각했고,

그에 맞는 도구로 Swagger를 선택하게 되었다.