[Spring Boot] API 문서화의 끝판왕: Swagger(Springdoc)와 REST Docs의 대결

백엔드 개발자가 API 100개를 열심히 다 만들었습니다. 이제 이 API를 가져다 써야 하는 프론트엔드(React, iOS) 개발자와 핏대 높여 싸울 시간이 왔습니다. "회원가입 파라미터가 userName인가요 user_name인가요?", "에러가 났을 때 리턴되는 JSON 응답 양식 좀 엑셀로 정리해서 주세요!" 과거에는 노션(Notion)이나 엑셀에 한 땀 한 땀 API 스펙을 수동으로 적어주었습니다. 하지만 백엔드 코드가 수정될 때 문서 업데이트를 깜빡하는 순간, 코드는 최신인데 문서는 구버전인 '거짓말 문서'가 되어버리고 프론트엔드의 비난을 한 몸에 받게 됩니다. 이 끔찍한 비효율과 커뮤니케이션 비용을 제로(0)로 만들기 위해 등장한 구원자가 바로 "자바 코드를 읽어서 자동으로 멋진 웹페이지 API 문서를 만들어주는 도구"입니다.

이번에는 전 세계 양대 산맥으로 꼽히는 Swagger(Springdoc OpenAPI)와 Spring REST Docs의 극명한 차이점 비교와 실무 적용 가이드에 대하여 다뤄보겠습니다.

🌟 1. Swagger (Springdoc OpenAPI): 쉽고 강력하고 화려하다

Swagger(스웨거)는 현재 전 세계에서 가장 대중적으로 쓰이는 API 문서화 도구입니다. 과거 Springfox 라이브러리가 유행했으나 업데이트가 끊겨, Spring Boot 3.x 시대에는 무조건 'Springdoc OpenAPI'를 사용해야 합니다.

장점:
- 적용이 미친 듯이 쉽습니다. 의존성 한 줄만 넣고 서버 켜면 /swagger-ui.html 주소에 문서가 뚝딱 만들어집니다.
- [Try it out] 이라는 버튼을 제공해서, 프론트엔드 개발자가 포스트맨(Postman)을 안 켜고도 문서 페이지 안에서 직접 파라미터를 넣고 API를 호출하며 테스트해 볼 수 있습니다. (압도적 장점)

단점 (치명적):
문서를 예쁘게 꾸미려면 컨트롤러 코드에 Swagger 전용 어노테이션(@Operation, @ApiResponse)을 지저분하게 덕지덕지 발라야 합니다. 비즈니스 로직(1줄)보다 문서화 어노테이션(10줄)이 더 길어지는 현상이 발생해 코드가 더러워집니다.

// Swagger(Springdoc) 적용 예시: 코드가 매우 지저분해지는 단점
@RestController
@Tag(name = "회원 API", description = "회원 가입 및 조회를 담당합니다.")
public class UserController {

    @Operation(summary = "회원가입", description = "신규 유저를 등록합니다.")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "성공"),
        @ApiResponse(responseCode = "400", description = "이메일 형식 오류")
    })
    @PostMapping("/users")
    public ResponseEntity<User> signup(@RequestBody UserDto dto) {
        return ResponseEntity.ok(userService.signup(dto));
    }
}

🧪 2. Spring REST Docs: 코드 침투 제로, 테스트 강제화의 미학

Swagger의 '더러운 코드'를 혐오하는 우아한(?) 개발자 진영(예: 배달의민족, 토스 등 기술 블로그)에서 사랑하는 방식이 Spring REST Docs입니다.

장점:
- 프로덕션 코드(Controller)에 단 하나의 어노테이션도 추가되지 않습니다. 코드가 극도로 깨끗하게 유지됩니다.
- (핵심) 테스트 코드를 통과해야만 문서가 만들어집니다. 즉, 테스트 코드를 짜지 않거나 테스트가 실패하면(로직이 꼬이면) 아예 API 문서가 안 나옵니다. 따라서 프론트엔드는 "이 API 문서는 100% 작동이 보장되는 진실된 문서다"라고 확신할 수 있습니다.

단점:
- 적용하기가 끔찍하게 어렵고 진입 장벽이 높습니다.
- Swagger처럼 브라우저에서 버튼 눌러서 테스트해 보는 기능(Try it out)이 없습니다. 오직 정적인 HTML 문서만 예쁘게 보여줄 뿐입니다.

// REST Docs 적용 예시: 운영 코드가 아닌 '테스트 코드(MockMvc)' 파일에 문서화 로직을 적습니다.
mockMvc.perform(post("/users")
        .contentType(MediaType.APPLICATION_JSON)
        .content(objectMapper.writeValueAsString(dto)))
        .andExpect(status().isOk())
        .andDo(document("user-signup", // 🌟 테스트가 성공하면 user-signup.adoc 조각을 만들어라!
                requestFields(
                        fieldWithPath("email").description("유저 이메일"),
                        fieldWithPath("password").description("비밀번호")
                )));

⚖️ 3. 실무에서의 승자는? (하이브리드 전략)

대기업처럼 테스트 주도 개발(TDD) 문화가 강하게 잡혀있고 코드의 순수성을 중시한다면 REST Docs를 씁니다. 반면, 빠르게 기능을 치고 나가야 하는 스타트업이거나 프론트엔드와 핑퐁 테스트를 자주 해야 한다면 Swagger의 [Try it out] 기능을 포기할 수 없습니다.

최근에는 이 둘의 장점만 쏙 빼먹는 "REST Docs로 테스트 빡세게 해서 OpenAPI 스펙(JSON)을 추출한 뒤, 그걸 Swagger UI로 화려하게 그려주는 하이브리드(REST Docs + Swagger UI)" 구조도 인기입니다.

🎯 4. 마무리 및 다음 단계

지금까지 API 개발을 마친 후 프론트엔드와의 협업에서 발생하는 끔찍한 커뮤니케이션 비용을 0으로 만들어주는 자동화 문서 도구, 편리함의 끝판왕 Swagger(Springdoc)와 테스트 강제성을 부여하는 순수주의자 REST Docs의 장단점 및 실무 선택 가이드에 대해 다루어 보았습니다. 이제 거짓말 없는 API 스펙으로 평화로운 협업을 할 수 있게 되었습니다.

이제 모든 개발과 문서화가 끝나고 정말로 서버를 운영 중입니다. 그런데 치명적인 버그를 발견해서 소스코드를 수정하고 재배포(Deploy)를 해야 합니다. java -jar app.jar를 끄고 새 버전을 다시 켜는데 약 15초가 걸립니다. 이 15초 동안 사이트에 접속한 유저들은 "서버 연결할 수 없음(502 Bad Gateway)" 에러 창을 멍하니 쳐다보게 됩니다. 현대 인터넷 환경에서 1초의 다운타임(Downtime)은 곧 매출 하락입니다! 이어지는 25단계 포스팅에서는 "유저는 단 0.1초의 끊김도 느끼지 못한다!" 현대 인프라의 마법, Nginx(엔진엑스)를 활용한 블루/그린 무중단 배포(Zero-Downtime Deployment) 아키텍처에 대해 아주 뼈 때리게 파헤쳐 보겠습니다!