Spring Rest Docs

Controller 테스트 케이스에 Spring Rest Docs 적용하기

https://jaeyoungb.tistory.com/196 여기서 Spring Rest Docs를 사용하기 위한 준비를 마쳤고, 이제 Controller 테스트 케이스에 Spring Rest Docs를 적용시켜보자.

 

API 문서 생성을 위한 테스트 케이스 기본 구조

• (1) @WebMvcTest은 Controller를 테스트 하기 위한 전용 애너테이션, 괄호 안에는 테스트 대상 Controller 클래스를 지정
• (2) JPA에서 사용하는 Bean 들을 Mock 객체로 주입
  (Spring Boot 기반의 테스트는 항상 최상위 패키지 경로에 있는 xxxxxxxApplication 클래스를 찾아서 실행)
• (3) Spring Rest Docs에 대한 자동 구성
• (4) MockMvc 객체를 주입 받음
• (5) Controller 클래스가 의존하는 객체(주로 서비스 클래스와 Mapper)의 의존성을 제거

 

@SpringBootTest  vs  @WebMvcTest

@SpringBootTest 애너테이션은 @AutoConfigureMockMvc과 함께 사용되어 Controller를 테스트할 수 있다.
테스트 환경을 구성하는 것은 편리하지만, 실행 속도가 상대적으로 느리다.

@WebMvcTest 애너테이션은 Controller 테스트에 필요한 Bean만 ApplicationContext에 등록하기 때문에 실행 속도는 상대적으로 빠르다.
하지만, Controller에서 의존하고 있는 객체가 있다면 해당 객체에 대해서 Mock 객체를 사용하여 의존성을 일일이 제거해주어야 한다.

결과적으로, @SpringBootTest는 데이터베이스까지 요청 프로세스가 이어지는 통합 테스트에 주로 사용되고, @WebMvcTest는 Controller를 위한 슬라이스 테스트에 주로 사용한다.

 

 

API 문서 생성을 위한 API 스펙 정보 추가

MemberContorller의 postMember() 핸들러 메서드에 대한 API 스펙 정보 추가

 

• (1), (2) MemberController가 의존하는 객체와의 관계를 단절
• (3) postMember() 핸들러 메서드에 전송하는 request body
• (4)는 postMember() 핸들러 메서드가 응답으로 전송하는 response body
• (5), (6), (7) MemberController의 postMember()에서 의존하는 객체의 메서드 호출을 (1)과 (2)에서 주입 받은 Mock 객체를 사용해서 Stubbing
• (8) MockMvc의 perform() 메서드로 POST 요청을 전송
• (9) document(…) 메서드는 API 스펙 정보를 전달 받아서 실질적인 문서화 작업을 수행하는 RestDocumentationResultHandler 클래스에서 가장 핵심 기능을 하는 메서드
  • (9-1) API 문서 스니핏의 식별자 역할, 문서 스니핏은 post-member 디렉토리 하위에 생성
  • (9-2), (9-3) 문서 스니핏을 생성하기 전에 request와 response에 해당하는 문서 영역을 전처리하는 역할
    getRequestPreProcessor(), getResponsePreProcessor()는 문서에 표시되는 JSON 포맷의 request, response body를 예쁘게 표현
  • (9-4) requestFields(…)는 문서로 표현될 request body를 의미
  • (9-5) FieldDescriptortype(JsonFieldType.STRING)은 JSON 프로퍼티의 값이 문자열임을 의미
  • JSON Field Type에 대해
    • https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api-request-response-payloads-fields-json-field-types
  • (9-6) responseFields(…)는 문서로 표현될 response body를 의미
  • (9-7) fieldWithPath("data.memberId") 의 data.memberId는 data 프로퍼티의 하위 프로퍼티를 의미
  • API 문서화 작업을 수행하는 RestDocumentationResultHandler의 document() 메서드에 사용할 수 있는 파라미터에 대해
    • https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api

 

이후, 테스트 케이스를 실행시켜보면 다음과 같이 문서 스니핏이 생성된다.

 

생성된 스니핏을 이용한 API 문서화

테스트 케이스를 실행한 후, 'passed'의 결과를 얻고 나서 생긴 스니핏은 문서 일부에 포함되는 조각 모음이다.

이 조각 모음들을 완전한 문서로 만들기 위해서는 템플릿 문서가 필요하다.

 

먼저, src/docs/asciidoc 디렉토리를 생성하고 비어 있는 index.adoc 파일을 생성해준다.

Gradle 프로젝트의 경우, 템플릿 문서가 위치하는 디폴트 경로는 src/docs/asciidoc

 

 

생성한 index.adoc 파일에 템플릿 문서 내용을 추가

• (1) API 문서의 제목
• (2) API 문서를 생성자의 정보
• (1), (2) 사이에 있는 항목은 API 문서의 목차와 관련된 내용
• (3) API 문서의 생성 날짜
• (4) 우리가 테스트 케이스 실행을 통해 생성한 API 문서 스니핏을 사용하는 부분
  형식 : include::{snippets}/스니핏 문서가 위치한 디렉토리/스니핏 문서파일명.adoc[]

 

템플릿 문서를 HTML 파일로 변환

우측의 Gradle 탭에서 bootJar 또는 build를 더블 클릭한다.

 

빌드가 종료되면, src/main/resources/static/docs 디렉토리에 index.adoc 파일을 이용해 변환된 index.html 파일이 생성된다.

index.html

 

이제, Intellij에서 애플리케이션을 실행시키고, 웹 브러우저에 http://localhost:8080/docs/index.html을 입력한다.

웹 브라우저에서 확인한 Spring Rest Docs 기반 API 문서

 

정리

• Controller 테스트를 위한 테스트 케이스 실행으로 생성된 API 문서 스니핏은 템플릿 문서에 포함해서 사용
• 애플리케이션 빌드를 통해, 템플릿 문서를 HTML 파일로 변환
• 변환된 HTML 파일을 src/main/resources/static/docs 디렉토리에 위치시키면 웹 브라우저로 문서 확인 가능
• 문서 스니핏과 템플릿 문서를 이용해서 API 문서를 생성하는 방법에 대해
  • https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#working-with-asciidoctor