죽은 문서는 가라! Spring REST Docs로 100% 신뢰할 수 있는 API 명세서 만들기

Collaboration & Documentation

신뢰도 0% 문서는 이제 그만,
Spring REST Docs 도입 가이드

 

안녕하세요, code-resting입니다. 프론트엔드 개발자와 협업할 때 가장 곤혹스러운 순간이 언제인가요? 아마도 "문서에는 이 필드가 필수라고 되어 있는데, 실제 API를 호출하니 에러가 나요"라는 말을 들을 때일 것입니다. 오늘은 테스트 코드를 통과해야만 문서가 생성되는, 가장 정직한 문서화 도구인 Spring REST Docs를 소개합니다.

1. Swagger vs Spring REST Docs

두 도구는 지향하는 바가 명확히 다릅니다. 프로젝트의 성격에 따라 선택해야 합니다.

🛠️ Swagger (SpringDoc)

• 장점: 설정이 쉽고 API 테스트(Try it out)가 가능함.
• 단점: 비즈니스 코드에 어노테이션이 덕지덕지 붙어 가독성을 해침(코드 침해).

🛡️ Spring REST Docs

• 장점: 비즈니스 코드에 영향이 없음. 테스트 성공 시에만 문서가 갱신됨(신뢰도 100%).
• 단점: 모든 API에 대한 테스트 코드를 반드시 작성해야 함(러닝 커브).

2. Spring REST Docs의 동작 원리

단순히 코드를 읽는 것이 아니라, 테스트 실행 과정에서 캡처된 스니펫(Snippet)을 조합하여 문서를 만듭니다.

1. 테스트 코드 작성: MockMvc 등을 사용하여 API 테스트 코드를 짭니다.
2. 스니펫 생성: 테스트가 성공하면 build/generated-snippets 폴더에 요청/응답 정보가 .adoc 파일로 저장됩니다.
3. 문서 조립: 미리 준비한 index.adoc 파일에 이 스니펫들을 포함(include)시킵니다.
4. HTML 변환: Asciidoctor가 최종적으로 깔끔한 HTML 문서를 빌드합니다.

3. 실전 테스트 코드 예시

문서에 들어갈 필드 설명을 테스트 코드 내에서 명시합니다.

this.mockMvc.perform(get("/api/users/{id}", 1L))
    .andExpect(status().isOk())
    .andDo(document("user-get", 
        pathParameters(
            parameterWithName("id").description("사용자 식별자")
        ),
        responseFields(
            fieldWithPath("name").description("이름"),
            fieldWithPath("email").description("이메일")
        )
    ));

4. 결론: 무엇을 선택할까?

✅ Swagger: 빠른 프로토타이핑이 필요하거나, 사외 공용 API처럼 사용자 테스트 환경이 중요한 경우.

✅ REST Docs: 엄격한 품질 관리가 필요한 엔터프라이즈 환경, 테스트 커버리지를 강제하고 싶은 팀, 깨끗한 코드를 유지하고 싶은 경우.

💡 마치며

2026년의 백엔드 개발은 단순히 기능을 만드는 것을 넘어 **'지속 가능한 협업 체계'**를 구축하는 데 집중합니다. Spring REST Docs는 문서와 코드의 정합성을 보장해 주는 가장 강력한 도구입니다. 처음에는 번거롭더라도, 한번 도입하면 프론트엔드 팀의 신뢰도가 수직 상승하는 것을 경험하실 수 있습니다.

© 2026 code-resting. All rights reserved.