Rest Docs 사용법

API 문서화하는 방법

컨트롤러 클래스에서 마우스 우클릭하기.

[GoTo] -> [Test] 클릭.

기존에 테스트 클래스가 존재한다면, 해당 클래스 클릭하기.

없다면, [Create] 새로 만들기.

새로 만들었다면, test/java/com/kustism/backend/controller 폴더 아래에 생성되었는지 확인하기.

@AcitiveProfiles("test") -> application-test.yml 파일을 사용하겠다는 의미이다.

@ExtendWith(RestDocumentationExtension.class) -> Junit5 사용할 경우 추가해야 한다.

@WebMvcTest(AuthController.class) -> 해당 클래스를 테스트하겠다는 의미로만 알아두어도 된다.

@MockBean(JpaMetamodeMapplingContext.class) -> JpaAuditing 옵션을 사용하기 위해서 추가해야 한다.

여기까지가 테스트 클래스를 위한 설정이다.

멤버 변수로 선언된 것들 중 핵심은 아래와 같다.

@Autowired MockMvc mockMvc -> 테스트를 할 때, 내장 톰캣을 사용하는 것이 아닌 테스트만을 위한 Mock 객체를 이용한다. 어플리케이션 전체를 로딩하는 것이 아니라, 해당 클래스에 정의된 애들만 로딩한다.

@MockBean -> 가짜 객체로 만들 클래스에 붙이면 된다. 위의 테스트 클래스의 경우, IAuthService 클래스와 AuthService내에 선언된 멤버 변수들을 필요로 하기에 모두 선언해야 한다.

@Autowired ObjectMapper objectMapper -> 테스트 시, Request dto를 json 으로 넘기는 것을 테스트하기 위해서 매퍼를 이용해 string 타입으로 변환해야 한다.

mockMvc 객체를 위한 세팅으로 인코딩과 문서화를 위한 것이다.

@Test -> 테스트를 하겠다는 의미.

@DisplayName() -> 테스트하는 함수의 이름 혹은 api 이름 명시하기.

해당 api 에서 주고 받는 DTO를 미리 정의하기.

given() 함수에서는 요청을 받아서 하는 행위를 명시하고, willReturn() 함수에서는 그 결과를 명시한다.

Request body로 사용되는 객체는 objectMapper로 string으로 변환시킨다.

ResultActions는 mockMvc가 처리한 것에 대해 결과를 담고 있다.

문서화를 하는 코드이다.

왼쪽에 초록색 동그란 버튼을 누른다.

테스트에 성공하면 성공이라고 뜬다. 테스트에 성공한 뒤, build를 한다.

build 성공 시, 문서화 작업을 한다.

build / generated-snippets / 함수명 / ...

해당 경로에 build 결과물이 생성된다.

이를 가지고 아래 경로에 있는 api-doc.adoc 파일에 추가한다.

markdown 언어와 비슷하다. 사진에 나온 예제를 보고 그대로 내용물만 바꿔서 적으면 된다.