[RESTDocs] Spring RestDocs 적용하기

들어가기 전

이번 프로젝트를 진행하면서 API문서를 REST Docs를 사용해 만들기로 하였다. API 명세서를 REST Docs를 사용해서 작성하는건 처음이여서 프로젝트를 시작하기전에 이런저런 테스트를 진행해 보았다. 그럼 지금부터 알아보자!

REST Docs? 

Spring REST Docs는 정확하고 가독성 좋은 REST 문서를 제공하기 위한 프로젝트이다. Asciidoctor를 활용해서 테스트코드를 adoc으로 변환후 HTML로 변환시켜주는 방식을 사용한다. 대안으로 Markdown을 사용할 수도 있다.

 

Adoc?
adoc은 문서를 작성하기 위한 경량형 마크업 언어이다. asciidoctor를 통해 html이나 pdf등의 형태로 변환하여 활용이 가능하다.

 

먼저 Spring MVC의 test에서 제공하는 MockMvc로 테스트 코드를 작성하여 사용한다.여기서 REST Docs의 장점이 나온다. 바로 테스트 코드를 통해 REST API 문서를 작성해주기 때문에 테스트가 검증되었다면 작성되는 문서도 신뢰할수있다는 것이다.

 

REST Docs vs Swagger

스웨거를 사용하게 되면 프로덕션 코드에 문서화에 대한 코드가 포함되어, 가독성이 떨어지게된다. 그리고 API 스펙이 변경되었을때, 어노테이션을 변경하지 않으면 API 문서가 수정되지 않는다.

 

이에반해 REST Docs는 테스트코드를 작성하면서 API를 명세 할수있다. 또한 테스트코드를 통해 작성된 스니펫과 직접작성한 문서를 결합하여 최종적인 API 문서를 만들수있으므로 제품 코드에 영향이 없다. 하지만 테스트 기반으로 작성되다보니 테스트가 실패하면 문서를 생성할수가없고, 문서화를 위한 테스트를 작성해야한다는 점이다. TDD방식을 적용한다면 오히려 좋은게 아닐까?

 

MockMvc vs RestAssured

RestDocs에서 사용할수있는 2가지 방식이다. RestAssured는 별도의 구성을 하지않는다면, @SpringBootTest 와 함께 사용되어야하는데, @SpringBootTest는 스프링의 전체 빈을 컨텍스트에 띄어서 테스트 환경을 구동한다. 즉, 어플리케이션이 동작하는 실제환경과 동일하게 테스트를 진행하고 싶을때 사용한다. 이에 따라서 @SpringBootTest를 통해 모든 빈이 등록 되는 과정에서 느려지고 비용이 많이든다. 

 

이에반해 MockMvc 는 @SpringBootTest , @WebMvcTest 중 선택해서 사용이 가능하다. @WebMvcTest는 프레젠테이션 레이어의 빈들만 로드한다. 그리고 나머지 계층은 Mocking을 한다. 이런 방식으로 하나의 계층만을 테스트하는 것을 슬라이스 테스트라고 하며, 일반적으로 문서화를 위해 컨트롤러 테스트를 작성할때는 컨트롤러 이외의 계층을 Mocking하여 진행한다. 

 

 

REST Docs 사용

내가 구성한 환경은 아래와 같다.

• Java 11
• Gradle 8.8
• Spring 2.7

Gradle 설정

[플러그인 추가]

plugins {
    // ...

    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

Asciidoctor 플러그인을 적용한다.
- Gradle 7 버전 이상일 때 org.asciidoctor.jvm.convert 3.3.2 버전을 사용한다.
- Gradle 7 버전 미만일 때 org.asciidoctor.convert 2.4.0 버전을 사용한다.

 

[구성 추가]

configurations {
    // ...

    asciidoctorExt
}

Asciidoctor를 확장하는 종속성에 대한 구성을 선언한다.

 

[의존성 추가]

dependencies {
    // ...

    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

테스트 코드에서 MockMvc를 사용하기 위해 필요하다.

 

[변수 선언]

ext {
	snippetsDir = file('build/generated-snippets')
}

 

[작업 설정]

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

- test 작업 시 output을 위에서 설정한 snippetsDir에 담도록 한다.
- asciidoctor 작업은 test 작업을 의존하기에, test 작업을 먼저 수행하도록 한다.
- asciidoctor 작업에 필요한 input이 snippetsDir에 있는 것을 알 수 있다.
- 구성 추가에서 확장한 asciidoctorExt를 사용한다.

 

[Jar 빌드 작업]

bootJar {
    dependsOn asciidoctor
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

프로젝트를 Jar 파일로 생성시에 Rest Docs가 해당 경로에 위치할수 있도록 한다.

bootJar {
    dependsOn asciidoctor
    print ${asciidoctor.outputDir}
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

이때 혹시 ${asciidoctor.outputDir} 의 경로가 다른경우도 있다. 이를 방지하기 위해서 위와 같은 방법으로 outputDir의 위치를 찍어보고 위치를 변경해줘도 좋다.

 

여기까지는 필수로 적용해야하는 부분이고, 기본적으로 이렇게 작성된다면 build/docs/ 경로로 html 파일이 위치하게 된다. 이를 src/main/resources/static/docs 로 복사하는 작업은 아래 전체 코드에 추가되어있다.

 

[전체 코드]

/******* Start Spring Rest Docs *******/
ext {
    snippetsDir = file("$buildDir/generated-snippets")
}

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor.doFirst {
    delete file("src/main/resources/static/docs")
}

asciidoctor {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

bootJar {
    dependsOn asciidoctor
    from("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file("$buildDir/docs/asciidoc")
    into file("src/main/resources/static/docs")
}

build {
    dependsOn copyDocument
}
/******* End Spring Rest Docs *******/

test -> asciidoctor -> copyDocument -> build 순으로 작업이 진행되어 애플리케이션을 실행키면 http://localhost:8080/docs/파일명.html 경로를 통해 API 문서에 접근할 수 있다.

 

Adoc 설정

= ALARM API 문서
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 3

== 알림 가져오기

=== Request

include::{snippets}/alarm/postAlarm/http-request.adoc[]

=== Response

include::{snippets}/alarm/postAlarm/http-response.adoc[]

asciidoc 문법 참고

 

index.adoc
전체 코드를 연결해줄 홈 화면이라고 생각하면 된다. include를 통해 다른 파일을 연결해주면 된다!

= Spring REST Docs Test
:doctype: book
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:seclinks:

include::test.adoc[]

 

 

MockMvc 설정

[통합테스트 사용시]

@ExtendWith({RestDocumentationExtension.class})
@Transactional
@SpringBootTest
public class IntegrationTest {

    @Autowired
    protected WebApplicationContext webApplicationContext;

    protected MockMvc mockMvc;

    @BeforeEach
    protected void setUpAll(RestDocumentationContextProvider restDocumentationContextProvider) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
            .addFilter(new CharacterEncodingFilter("UTF-8", true))
            .apply(documentationConfiguration(restDocumentationContextProvider)
                .operationPreprocessors()
                .withRequestDefaults( // (1)
                    modifyUris().scheme("https").host("docs.api.com").removePort(), prettyPrint())
                .withResponseDefaults(prettyPrint()) // (2)
            )
            .build();
    }
}

MockMvcBuilders를 통해 MockMvc를 생성할 수 있다. 설정으로 WebApplicationContext를 사용하는데, 스프링에서 로드한 WebApplicationContext의 인스턴스로 동작하기에 컨트롤러는 물론 의존성까지 로드되어 완전한 통합테스트가 가능하다. 필터에 UTF-8을 강제하는 CharacterEncodingFilter을 추가하여 MockMvc 사용 시 한글 깨짐을 방지한다.

 RestDocument는 요청과 응답을 수정할 수 있는 전처리기를 제공한다.
(1) : 문서의 Request URI를 기본 http://localhost:8080에서 https://docs.api.com으로 변경하고, 예쁘게 출력할 수 있도록 한다.
(2): 문서의 Response를 예쁘게 출력할 수 있도록 한다.

 통합 테스트를 수행하는 테스트는 위의 클래스를 상속받아서 사용하면 된다.

 

 

[직접 MockMvc 만들어서 사용]

//Test

@AutoConfigureRestDocs
@WithMockUser
@WebMvcTest(AlarmController.class)
public class AlarmControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper; //DTO to Json

    @MockBean
    private AlarmService alarmService; //mocking 

    @DisplayName("알람 생성")
    @Test
    void createAlarm() throws Exception {
        //given
        AlarmDto alarmDto = new AlarmDto("test12", "test22");
        Alarm alarm = Alarm.builder()
                .alarmId(1L)
                .testContent1("test1")
                .testContent2("test2")
                .build();

        given(alarmService.createAlarm(any(Alarm.class)))
                .willReturn(alarm);

        //when & then
        mockMvc.perform(MockMvcRequestBuilders.get("/alarm")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(alarmDto))
                        .with(SecurityMockMvcRequestPostProcessors.csrf()))
                .andDo(MockMvcResultHandlers.print())
                .andDo(MockMvcRestDocumentation.document("alarm/postAlarm",
                        Preprocessors.preprocessRequest(prettyPrint()),
                        Preprocessors.preprocessResponse(prettyPrint())))
                .andExpect(MockMvcResultMatchers.status().isCreated());
    }
}

 

//Controller

@RestController
@RequestMapping
@RequiredArgsConstructor
public class AlarmController {

    private final AlarmService alarmService;

    @GetMapping("/alarm")
    public ResponseEntity postAlarm(@RequestBody AlarmDto alarmDto) {
        Alarm alarm = Alarm.builder()
                .alarmId(1L)
                .testContent1("alarmDto.getTestContent1()")
                .testContent2("alarmDto.getTestContent2()")
                .build();

        return new ResponseEntity<>(alarmService.createAlarm(alarm), HttpStatus.CREATED);
    }
}

 

//DTO

@Getter
@Setter
@AllArgsConstructor
public class AlarmDto {

        private String testContent1;

        private String testContent2;
}

 

//Entity

@Entity
@Builder
@Getter
public class Alarm {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long alarmId;

    private String testContent1;

    private String testContent2;
}

 

//service -> 이부분도 Mocking 된다.

@Service
public class AlarmService {

    public Alarm createAlarm(Alarm alarm) {

        return Alarm.builder().alarmId(1L).testContent1("111").testContent2("222").build();
    }
}

 

 

결과

이렇게 표출이 되게 된다.

 

 

 

참고

RestDocs 공식문서