[Spring Boot] "API 명세서, 엑셀로 쓰세요?" Swagger vs REST Docs 승자는?

 

안녕하세요! 개발자의 귀차니즘을 해결해 주는 IT 블로거입니다.

API 문서는 개발자에게 계륵 같은 존재입니다. 없으면 협업이 불가능하고, 있으면 관리하기 너무 귀찮으니까요. 그래서 우리는 문서 자동화 도구를 사용합니다.

스프링 부트 진영에는 두 가지 강력한 도구가 있습니다.

1. Swagger (Springdoc): "쉽고 빠르고 예쁘다!" (Annotations 기반)
2. Spring REST Docs: "테스트를 통과해야만 문서가 나온다!" (Test 기반)

과연 우리 팀에는 무엇이 맞을까요?

---

1. 쉽고 화려한: Swagger (Springdoc)

가장 많이 쓰이는 도구입니다. 예전엔 springfox를 썼지만, 지금은 업데이트가 멈춰서 springdoc-openapi 라이브러리를 사용합니다.

장점: 설정이 3분 컷!

build.gradle에 의존성 하나만 추가하면 끝납니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

서버를 켜고 http://localhost:8080/swagger-ui/index.html에 접속하면 화려한 UI가 반겨줍니다.

특징: 코드에 설명을 적는다

컨트롤러에 어노테이션을 덕지덕지 붙여야 합니다.

@Tag(name = "회원 API", description = "회원 관련 기능")
@RestController
public class MemberController {

    @Operation(summary = "회원 가입", description = "신규 회원을 등록합니다.")
    @PostMapping("/signup")
    public ResponseEntity<Void> signup(...) { ... }
}

• Good: 적용이 정말 쉽습니다. "Try it out" 버튼을 눌러서 포스트맨(Postman)처럼 API를 직접 테스트해 볼 수 있습니다.
• Bad: 프로덕션 코드(Controller)에 문서용 코드가 섞여서 지저분해집니다. 로직이 바뀌어도 문서를 안 고치면 꽝입니다.

---

2. 신뢰의 상징: Spring REST Docs

우아한형제들(배달의민족), 카카오 등 기술력이 좋은 기업들이 선호하는 도구입니다.

특징: 테스트 코드가 문서가 된다

지난 시간에 배운 MockMvc 테스트 코드를 작성하면, 실행 결과로 문서 조각(Snippet)이 생성됩니다. 이 조각들을 모아서 HTML 문서를 만듭니다.

// 테스트 코드 (ControllerTest)
mockMvc.perform(post("/signup")
        .content(json))
        .andDo(document("signup", // 문서 조각 이름
                requestFields(
                        fieldWithPath("name").description("회원 이름"),
                        fieldWithPath("email").description("이메일")
                )
        ));

• Good: 프로덕션 코드가 깨끗합니다. (어노테이션 없음) 무엇보다 테스트가 실패하면 문서가 안 만들어집니다. 즉, "문서와 코드는 100% 일치한다"는 강력한 신뢰를 줍니다.
• Bad: 적용 난이도가 높습니다. (설정 복잡) 테스트 코드를 강제로 짜야 합니다. (이건 장점이기도 하죠?)

---

3. 한눈에 비교: 뭘 써야 할까요?

특징	Swagger (Springdoc)	Spring REST Docs
적용 난이도	하 (매우 쉬움)	상 (설정 복잡)
코드 오염	있음 (Controller가 지저분해짐)	없음 (완전 분리)
신뢰성	중 (개발자가 까먹으면 불일치 발생)	상 (테스트 통과 못 하면 빌드 실패)
테스트 기능	제공 (UI에서 바로 호출 가능)	미제공 (문서만 보여줌)
추천 대상	초기 스타트업, 내부 어드민, 빠른 개발	대규모 서비스, 외부 공개 API, 품질 중시

---

4. 결론: 상황에 맞춰 고르세요!

• "우리 팀은 인원도 적고, 당장 기능 개발하기도 바빠요!"
  👉 Swagger를 추천합니다. 일단 빠르게 만들고 UI로 소통하세요.
• "API가 외부에 공개되거나, 앱이랑 통신하는데 문서가 틀리면 대형 사고예요!"
  👉 Spring REST Docs를 추천합니다. 초기 설정은 힘들지만, 유지보수 단계에서는 빛을 발합니다.

---

마치며

문서화는 개발의 끝이 아니라 협업의 시작입니다. 엑셀 파일 던져주고 "이거 보세요" 하는 대신, 세련된 URL 링크 하나로 "여기서 테스트해 보세요!"라고 말하는 멋진 개발자가 되어보세요.

다음 포스팅에서는 "내 요청은 누가 가로채는가?" Spring Boot의 수문장: Filter와 Interceptor의 차이점과 활용법에 대해 알아보겠습니다.