Spring REST Docs란?

Spring REST Docs

Spring REST Docs는 스프링에서 RESTful 서비스 문서 작성을 도와주는 도구로

테스트 코드를 기반으로 API 문서 조각(Snippets)을 생성하고, 그 조각을 모아서 최종 문서를 만드는 방식

 

Swagger와 다르게 테시트 코드를 기반으로 API 문서를 생성하기 때문에 프로덕션 코드에 영향을 주지 않고, API에 대한 다양한 정보를 제공함

 

테스트 코드를 기반으로 한다는 것은 API 문서를 생성하려면 반드시 테스트 코드를 작성해서 테스트에 성공해야 한다는 뜻

API 문서가 생성되었다는 것은 모든  테스트를 통과했다는 의미

 

즉, 서비스의 신뢰도가 상승하는 것

 

하지만, Swagger와 달리 페이지 내에서 바로 API를 실행해볼 수 없기 때문에 API를 실행하려면 포스트맨이나 curl 등을 사용해야 한다는 것

장점

• 테스트 코드를 기반으로 하기 때문에 신뢰도가 높음
• 프로덕션 코드에 영향을 주지 않음
• 자동으로 생성되기 때문에 변경된 API 사양에 바로 동기화됨

단점

• 적용하는 과정이 복잡함
• 페이지 내에서 바로 API를 실행할 수 없음

REST Docs를 사용하는 이유

API 문서에서 가장 무서운 것이 문서와 실제 설계된 API가 다를 때임

Swagger는 코드 기반 자동 생성이라 실제 응답과 달라도 문서가 깨지지 않음

 

하지만, REST Docs는 테스트가 실패하면 문서 생성도 실패해, 문서와 코드가 항상 일치함

 

Spring REST Docs의 전체 흐름

1. 테스트 코드 작성
2. 테스트 실행
3. Snippets 생성 (요청/응답 정보)
4. Snippets 파일 저장
5. AsciiBoc 문서에서 include
6. HTML/PDF로 변환

아키텍처 관점

[ Controller ]
      ↓
[ MockMvc Test ]
      ↓
document("api-name")
      ↓
[ build/generated-snippets/api-name/*.adoc ]
      ↓
[ src/docs/asciidoc/index.adoc ]
      ↓ include
[ asciidoctor ]
      ↓
[ HTML API 문서 생성 ]

 

프로젝트 세팅

build.gradle.kts

1. 의존성 추가

plugins{
	id("org.asciidoctor.jvm.convert) version "3.3.2"
}
configurations{
	create("asciidoctor")
}
dependencies{
	testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
    add("asciidoctor",("org.springframework.restdocs:spring-restdocs-asciidoctor"))
}

 

2. snippets 저장 경로 설정

val snippetsDir by extra {file("build/generated-snippets")}

tasks.test{
    useJUnitPlatform()
    outputs.dir(snippetsDir)
}

tasks.named<org.asciidoctor.gradle.jvm.AsciidoctorTask>("asciidoctor") {
    inputs.dir(snippetsDir)
    dependsOn(tasks.test)
}

• 테스트 실행 -> snipptes 생성
• asciidoctor 실행 -> HTML 생성

snippets 저장 경로를 설정하는 이유

Spring REST Docs는 Swagger처럼 API 문서를 바로 생성하지 않음

대신 테스트 실행 시 문서 조각(snippet)을 만들고, 이를 모아서 최종 문서를 생성하는 방식

 

전체 흐름

테스트 실행 → snippet 생성 → AsciiDoc에서 include → HTML 변환

 

1. Snippet은 중간 산출물

테스트 코드에서 

.andDo(document("get-user"));

 

테스트 실행 시 아래와 같은 파일이 생성됨

build/generated-snippets/get-user/
 ├── http-request.adoc
 ├── http-response.adoc
 └── response-fields.adoc

이 파일들은 최종 문서가 아니라 AsciiDoc에서 include로 불러오는 문서 조각임

 

2. 경로 설정이 필요한 이유

• AsciiDoc이 snippet 위치를 알아야하기 때문
• Gradle 빌드 파이프라인을 연결하기 위해
  • test -> snippet 생성 -> asciidoctor -> HTML 생성
  • test가 snippet을 생성하고
  • asiidoctor가 그 결과를 입력으로 사용
  • 빌드 순서를 보장하는 역할

 

실행결과

 

정상적으로 generated-snippets가 생성됨

 

테스트

테스트컨트롤러 TetsController.kt

package com.social.study.test

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/test")
class TestController {
    @GetMapping
    fun test(): Map<String,String>{
        return mapOf("message" to "Hello World!")
    }
}

 

테스트 패키지 내부의 테스트 코드

package com.social.study.test

import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document
import org.springframework.restdocs.operation.preprocess.Preprocessors.*
import org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath
import org.springframework.restdocs.payload.PayloadDocumentation.responseFields
import org.springframework.security.test.context.support.WithMockUser
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status

@AutoConfigureRestDocs
@SpringBootTest
@AutoConfigureMockMvc
class TestControllerTest(
    @Autowired val mockMvc: MockMvc
) {
    @WithMockUser
    @Test
    fun `test api documentation`(){
        mockMvc.perform(get("/test"))
            .andExpect(status().isOk)
            .andDo(
                document("test-api-documentation",
                    preprocessRequest(prettyPrint()),
                    preprocessResponse(prettyPrint()),
                    responseFields(
                        fieldWithPath("message")
                            .description("Hello World!")
                    ))
            )
    }
}

 

실행 결과

index.html이 생성됨

html 페이지