05. 02 TIL : RestDocs 적용 실습

학습 자료 출처 : https://spring.io/guides/gs/testing-restdocs/

 

스프링 공식 가이드가 제공하는 실습 프로젝트 : https://github.com/spring-guides/gs-testing-restdocs

 

참고한 글 : https://techblog.woowahan.com/2597/

 

학습 목표 : Spring 어플리케이션의 API를 JUnit과 MockMvc 라이브러리, 그리고 RestDocs를 활용해 API 문서화

 

왜 Rest Docs?

- 테스트가 성공하지 않으면 문서가 만들어지지 않으므로 Rest Docs 문서화가 완료되었다는 것은 테스트 코드 및 프로덕션 코드가 올바르게 기능한다는 의미이므로 API의 신뢰도를 높이고 테스트 코드를 검증할 수 있다.  

 

1. 어플리케이션 생성 및 실행

1) HomeController.java 생성

2) TestingRestdocsApplication.java 

package com.example.testingrestdocs;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class TestingRestdocsApplication {

	public static void main(String[] args) {
		SpringApplication.run(TestingRestdocsApplication.class, args);
	}
}

* 되새겨보는 스프링 부트 빌드 시 사용하는 주석

@SpringBootApplication : 다음의 주석을 추가할 수 있는 편의 주석

- @Configuration : 애플리케이션 컨텍스트를 위한 빈을 정의하는 설정 클래스에 대해 Spring Boot가 알 수 있도록 주석 표시

- @EnableAutoConfiguration : 클래스 경로 설정 등 spring.factories 내부 설정들이 조건에 따라 적용이 되어 빈이 생성이 되고, 스프링 부트 어플리케이션이 실행될 수 있게 만들어준다.

- @EnableWebMvc : 어플리케이션이 웹에서 동작할 수 있도록 Spring Mvc 프레임워크의 주요 기능을 활성화할 수 있다. spring의 DispatcherServlet 등록, ViewResolver 설정, HandlerMapping 등록, MessageConverter 활성화, StaticResourceHandler 등록

https://cdaosldk.tistory.com/54

스프링 입문 강의 노트 정리 (1) : 프로젝트 환경설정

- @ComponentScan : @Component 및 스테레오 타입 어노테이션이 부여된 클래스를 스캔해 빈으로 등록

2. 테스트 자동화

1) Junit 및 Spring Rest Docs 종속성 추가 : @MockMvc 사용

2) 통합 테스트를 실행할 테스트 코드 작성

3) @Service는 Mock 객체를 활용한다.

4) Controller Test 작성

package com.example.testingrestdocs;

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.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(HomeController.class)
// apply(documentationConfiguration(restDocumentation))설정 자동화
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

	@Autowired
	private MockMvc mockMvc;

	@Test
	public void shouldReturnDefaultMessage() throws Exception {
		this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())
				.andExpect(content().string(containsString("Hello, World")))
				.andDo(document("home"));
	}
}

5) 스니펫이 생성되는 디렉토리를 설정한다.

6) 테스트 후 asciidoctor 실행 설정 ~ asciidoctor는 adoc 파일을 html 등으로 바꿔주는 도구

 

3. 문서 작성

1) 생성된 adoc 스니펫을 모아 .adoc 파일을 생성하고 문서를 작성한다.

2) asciidoctor를 실행해 html 문서를 생성할 수 있다.

3) jar에 문서를 추가해 스프링 부트 어플리케이션 빌드 시 html 문서를 어플리케이션에서 제공할 수 있도록 한다.