[중앙정보기술인재개발원] 114일차

Spring Rest Docs 복습

Spring Rest Docs의 가장 큰 특징은 Controller의 슬라이스 테스트를 통해 테스트가 통과되어야지만 API 문서가 정상적으로 만들어진다는 것입니다.

이러한 특징으로 인해 Spring Rest Docs는 테스트를 중요하게 생각하는 개발자들에게 각광받는 기술 중 하나입니다.

이번 시간부터 우리가 만든 커피 주문 애플리케이션의 API 문서를 Spring Rest Docs를 통해 만들어 보도록 하겠습니다.

이번 유닛이 끝나면 여러분들이 만든 API 문서를 클라이언트 쪽에 자신 있게 제공할 수 있을 거라고 생각합니다.

Spring Rest Docs의 API 문서 생성 흐름

Spring Rest Docs를 이용해서 API 문서를 생성하기 위해서는 [그림 3-84]와 같이 Spring Rest Docs가 API 문서를 생성하는 흐름을 이해하고 있어야 합니다.

[그림 3-84] Spring Rest Docs의 API 문서 생성 흐름

 

1. 테스트 코드 작성
   1. 슬라이스 테스트 코드 작성 ⅰ. Spring Rest Docs는 Controller의 슬라이스 테스트와 밀접한 관련이 있다고 했습니다. 여러분들이 학습한 Controller에 대한 슬라이스 테스트 코드를 먼저 작성합니다.
   2. API 스펙 정보 코드 작성 ⅰ. 슬라이스 테스트 코드 다음에 Controller에 정의되어 있는 API 스펙 정보(Request Body, Response Body, Query Parameter 등)를 코드로 작성합니다.
2. test 태스크(task) 실행
   1. 작성된 슬라이스 테스트 코드를 실행합니다. ⅰ. 하나의 테스트 클래스를 실행시켜도 되지만 일반적으로 Gradle의 빌드 태스크(task)중 하나인 test task를 실행시켜서 API 문서 스니펫(snippet)을 일괄 생성합니다. (스니펫에 대해서는 아래에서 설명하겠습니다)
   2. 테스트 실행 결과가 “passed”이면 다음 작업을 진행하고, “failed”이면 문제를 해결하기 위해 테스트 케이스를 수정한 후, 다시 테스트를 진행해야 합니다.
3. API 문서 스니펫( .adoc 파일) 생성
   1. 테스트 케이스의 테스트 실행 결과가 “passed”이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니펫이 .adoc 확장자를 가진 파일로 생성됩니다.

스니펫(snippet)은 일반적으로 코드의 일부 조각을 의미하는 경우가 많은데 여기서는 문서의 일부 조각을 의미합니다.

스니펫은 테스트 케이스 하나당 하나의 스니펫이 생성되며, 여러 개의 스니펫을 모아서 하나의 API 문서를 생성할 수 있습니다.

1. API 문서 생성
   1. 생성된 API 문서 스니펫을 모아서 하나의 API 문서로 생성합니다.
2. API 문서를 HTML로 변환
   1. 생성된 API 문서를 HTML 파일로 변환합니다.
   2. HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있습니다.

Spring Rest Docs 설정

Spring Rest Docs가 API 문서 생성 작업을 정상적으로 수행할 수 있도록 기본적인 설정 작업을 먼저 해 주어야 합니다.

1. build.gradle 설정
2. API 문서 스니펫을 사용하기 위한 템플릿 API 문서 생성

✔ build.gradle 설정

 

plugins {
	id 'org.springframework.boot' version '2.7.1'
	id 'io.spring.dependency-management' version '1.0.11.RELEASE'
	id "org.asciidoctor.jvm.convert" version "3.3.2"    // (1)
	id 'java'
}

group = 'com.springboot'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
	mavenCentral()
}

// (2)
ext {
	set('snippetsDir', file("build/generated-snippets"))
}

// (3)
configurations {
	asciidoctorExtensions
}

dependencies {
        // (4)
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

        // (5)
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'

	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	implementation 'org.springframework.boot:spring-boot-starter-validation'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	compileOnly 'org.projectlombok:lombok'
	runtimeOnly 'com.h2database:h2'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	implementation 'org.mapstruct:mapstruct:1.5.1.Final'
	annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.1.Final'
	implementation 'org.springframework.boot:spring-boot-starter-mail'

	implementation 'com.google.code.gson:gson'
}

// (6)
tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

// (7)
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

// (8)
task copyDocument(type: Copy) {
	dependsOn asciidoctor            // (8-1)
	from file("${asciidoctor.outputDir}")   // (8-2)
	into file("src/main/resources/static/docs")   // (8-3)
}

build {
	dependsOn copyDocument  // (9)
}

// (10)
bootJar {
	dependsOn copyDocument    // (10-1)
	from ("${asciidoctor.outputDir}") {  // (10-2)
		into 'static/docs'     // (10-3)
	}
}

[코드 3-212] Spring Rest Docs 설정이 추가된 build.gradle 전체 코드

1. (1)에서는 .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해 주는 Asciidoctor를 사용하기 위한 플러그인을 추가합니다.
2. (2)에서는 ext 변수의 set() 메서드를 이용해서 API 문서 스니펫이 생성될 경로를 지정합니다.
3. (3)에서는 AsciiDoctor에서 사용되는 의존 그룹을 지정하고 있습니다. :asciidoctor task가 실행되면 내부적으로 (3)에서 지정한 ‘asciidoctorExtensions’라는 그룹을 지정합니다.
4. (4)에서 'org.springframework.restdocs:spring-restdocs-mockmvc'를 추가함으로써 spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가됩니다.
5. (5)에서 spring-restdocs-asciidoctor 의존 라이브러리를 추가합니다. (3)에서 지정한 asciidoctorExtensions 그룹에 의존 라이브러리가 포함이 됩니다.
6. (6)에서는 :test task 실행 시, API 문서 생성 스니펫 디렉토리 경로를 설정합니다.
7. (7)에서는 :asciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 :asciidoctor task에 asciidoctorExtensions을 설정합니다.
8. (8)은 :build task 실행 전에 실행되는 task입니다. :copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs 에 copy 되며, copy 된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용할 수 있습니다.
   1. (8-1)에서는 :asciidoctor task가 실행된 후에 task가 실행되도록 의존성을 설정합니다.
   2. (8-2)에서는 "build/docs/asciidoc/" 경로에 생성되는 index.html을 copy한 후,
   3. (8-3)의 "src/main/resources/static/docs" 경로로 index.html을 추가해 줍니다.
9. (9)에서는 :build task가 실행되기 전에 :copyDocument task가 먼저 수행되도록 합니다.
10. (10)에서는 애플리케이션 실행 파일이 생성하는 :bootJar task 설정입니다.
    1. (10-1)에서는 :bootJar task 실행 전에 :copyDocument task가 실행되도록 의존성을 설정합니다.
    2. (10-2)와 (10-3)에서는 Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가해 줍니다. jar 파일에 index.html을 추가해 줌으로써 웹 브라우저에서 접속(http://localhost:8080/docs/index.html) 후, API 문서를 확인할 수 있습니다.

(8)에서 copy되는 index.html은 외부에 제공하기 위한 용도이고, (10)에서는 index.html을 애플리케이션 실행 파일인 jar 파일에 포함해서 웹 브라우저에서 API 문서를 확인하기 위한 용도라는 것을 기억하세요.

 

✔ API 문서 스니펫을 사용하기 위한 템플릿(또는 source 파일) 생성

build.gradle에 API 문서 생성을 위한 설정이 완료되었습니다.

마지막으로 할 일은 API 문서 스니펫이 생성되었을 때 이 스니펫을 사용해서 최종 API 문서로 만들어 주는 템플릿 문서(index.adoc)를 생성하는 것입니다.

• Gradle 기반 프로젝트에서는 아래 경로에 해당하는 디렉토리를 생성해 주어야 합니다.
  • src/docs/asciidoc/
• 다음으로 src/docs/asciidoc/ 디렉토리 내에 비어있는 템플릿 문서(index.adoc)를 생성해 주면 됩니다. (뒤에서 한번 더 언급합니다)

드디어 Spring Rest Docs를 사용하기 위한 사전 준비는 끝났습니다

이제 Controller를 테스트할 테스트 케이스를 작성하고, 해당 Controller에 대한 API 스펙 정보를 테스트 케이스에 추가해 주면 API 문서 스니펫을 생성할 수 있습니다.

 

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

API 문서 생성을 위한 사전 준비 작업은 끝났습니다.

이제 Controller에 대한 테스트 케이스를 작성하고, API 문서화를 위한 API 스펙 정보를 테스트 케이스에 추가해 봅시다.

 

API 문서 생성을 위한 슬라이스 테스트 케이스 작성

 

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

 

package com.springboot.restdocs.member;

import com.springboot.member.controller.MemberController;
import com.springboot.member.mapper.MemberMapper;
import com.springboot.member.service.MemberService;
import com.google.gson.Gson;
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.boot.test.mock.mockito.MockBean;
import org.springframework.data.jpa.mapping.JpaMetamodelMappingContext;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;

@WebMvcTest(MemberController.class)   // (1)
@MockBean(JpaMetamodelMappingContext.class)   // (2)
@AutoConfigureRestDocs    // (3)
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;  // (4)

    @MockBean
	  // (5) 테스트 대상 Controller 클래스가 의존하는 객체를 Mock Bean 객체로 주입받기

    @Test
    public void postMemberTest() throws Exception {
        // given
        // (6) 테스트 데이터

        // (7) Mock 객체를 이용한 Stubbing

        // when
        ResultActions actions =
                mockMvc.perform(
                     // (8) request 전송
                );

        // then
        actions
                .andExpect(// (9) response에 대한 기대 값 검증)
                .andDo(document(
                            // (10) API 문서 스펙 정보 추가
                 ));
    }
}

[코드 3-213] API 문서 생성을 위한 테스트 케이스 기본 구조

 

코드 3-213은 Spring Rest Docs를 이용해 API 문서를 생성하기 위한 테스트 케이스의 기본 구조입니다.

1. (1)에서는 @SpringBootTest 애너테이션을 사용하지 않고, @WebMvcTest 애너테이션을 사용했습니다. @WebMvcTest 애너테이션은 Controller를 테스트하기 위한 전용 애너테이션입니다. @WebMvcTest 애너테이션의 괄호 안에는 테스트 대상 Controller 클래스를 지정합니다.
2. (2)는 JPA에서 사용하는 Bean 들을 Mock 객체로 주입해 주는 설정입니다. Spring Boot 기반의 테스트는 항상 최상위 패키지 경로에 있는 xxxxxxxApplication 클래스를 찾아서 실행합니다.

@EnableJpaAuditing
@SpringBootApplication
public class Section3Week3RestDocsApplication {

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

}

@EnableJpaAuditing 애너테이션이 추가되어 있는 것 보이나요?

이처럼 @EnableJpaAuditing을 xxxxxxApplication 클래스에 추가하게 되면 JPA와 관련된 Bean을 필요로 하기 때문에 @WebMvcTest 애너테이션을 사용해서 테스트를 진행할 경우에는 코드 3-213의 (2)와 같이 JpaMetamodelMappingContext를 Mock 객체로 주입해 주어야 합니다.

1. (3)에서는 Spring Rest Docs에 대한 자동 구성을 위해 @AutoConfigureRestDocs를 추가해 줍니다.
2. (4)에서 MockMvc 객체를 주입받습니다.
3. (5)에서는 Controller 클래스가 의존하는 객체(주로 서비스 클래스, Mapper)의 의존성을 제거하기 위해 @MockBean 애너테이션을 사용해서 Mock 객체를 주입받습니다.
4. (6)에서는 HTTP request에 필요한 request body나 query parmeter, path variable 등의 데이터를 추가합니다.
5. (7)에서는 (5)에서 주입받은 Mock 객체가 동작하도록 Mockito에서 지원하는 given() 등의 메서드로 Stubbing 해 줍니다.
6. (8)에서는 MockMvc의 perform() 메서드로 request를 전송합니다. MockMvc의 perform() 메서드는 슬라이스 테스트에서 여러분이 사용했던 방법과 동일합니다.
7. (9)에서는 response를 검증합니다. ResultActions의 .andExpect() 역시 슬라이스 테스트에서 사용했던 방법과 동일하게 검증을 진행하면 됩니다.
8. 마지막으로 (10)에서 테스트 수행 이후, API 문서를 자동 생성하기 위한 해당 Controller 핸들러 메서드의 API 스펙 정보를 document(…)에 추가해 줍니다..andDo(…) 메서드는 andExpect()처럼 어떤 검증 작업을 하는 것이 아니라 일반적인 동작을 정의하고자 할 때 사용됩니다.
9. document(…) 메서드는 API 문서를 생성하기 위해 Spring Rest Docs에서 지원하는 메서드입니다.

@SpringBootTest vs @WebMvcTest

우리가 [테스팅] 유닛에서는 @SpringBootTest + @AutoConfigureMockMvc 애너테이션으로 Controller의 테스트를 진행했었습니다.

@SpringBootTest와 @WebMvcTest의 차이점은 무엇일까요? 먼저 @SpringBootTest 애너테이션은 @AutoConfigureMockMvc과 함께 사용되어 Controller를 테스트할 수 있는데, 프로젝트에서 사용하는 전체 Bean을 ApplicationContext에 등록하여 사용합니다. 한마디로 테스트 환경을 구성하는 것은 편리하긴 한데 실행 속도가 상대적으로 느립니다.

@WebMvcTest 애너테이션의 경우 Controller 테스트에 필요한 Bean만 ApplicationContext에 등록하기 때문에 실행 속도는 상대적으로 빠릅니다.

다만, Controller에서 의존하고 있는 객체가 있다면 해당 객체에 대해서 Mock 객체를 사용하여 의존성을 일일이 제거해 주어야 합니다.

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

처음부터 슬라이스 테스트에 @WebMvcTest 애너테이션을 사용하면 되는데 왜 @SpringBootTest 애너테이션을 사용했냐고 의아해 할 수도 있습니다.

여러분들이 여러 가지 방식을 한꺼번에 학습하게 되면 머릿속이 더 혼란스러워질 거 같아서였습니다.

단계적인 기술 습득을 위해서라고 생각하고, Controller를 슬라이스 테스팅 하기 위해서는 지금부터 @WebMvcTest를 사용하면 되겠습니다.

 

Spring Rest Docs를 이용해 API 문서를 생성하기 위한 대략적인 기본 구조는 파악했으니, 현재 우리가 구현한 커피 주문 애플리케이션의 MemberController를 테스트하기 위한 테스트 케이스에 API 문서 생성을 위한 API 스펙 정보를 추가해 봅시다.

 

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

MemberController 테스트 케이스에 API 스펙 정보 추가

 

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

package com.springboot.restdocs.member;

import com.springboot.member.controller.MemberController;
import com.springboot.member.dto.MemberDto;
import com.springboot.member.entity.Member;
import com.springboot.member.mapper.MemberMapper;
import com.springboot.member.service.MemberService;
import com.springboot.stamp.Stamp;
import com.google.gson.Gson;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
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.boot.test.mock.mockito.MockBean;
import org.springframework.data.jpa.mapping.JpaMetamodelMappingContext;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.restdocs.payload.JsonFieldType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import java.util.List;

import static com.springboot.util.ApiDocumentUtils.getRequestPreProcessor;
import static com.springboot.util.ApiDocumentUtils.getResponsePreProcessor;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.startsWith;
import static org.mockito.BDDMockito.given;
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;

    // (1)
    @MockBean
    private MemberService memberService;

    // (2)
    @MockBean
    private MemberMapper mapper;

    @Autowired
    private Gson gson;

    @Test
    public void postMemberTest() throws Exception {
        // (3) given
        MemberDto.Post post = new MemberDto.Post("hgd@gmail.com", "홍길동", "010-1234-5678");
        String content = gson.toJson(post);

        // (4)
        given(mapper.memberPostToMember(Mockito.any(MemberDto.Post.class))).willReturn(new Member());

        // (5)
        Member mockResultMember = new Member();
        mockResultMember.setMemberId(1L);
        given(memberService.createMember(Mockito.any(Member.class))).willReturn(mockResultMember);

        // (6) when
        ResultActions actions =
                mockMvc.perform(
                        post("/v11/members")
                                .accept(MediaType.APPLICATION_JSON)
                                .contentType(MediaType.APPLICATION_JSON)
                                .content(content)
                );

        // then
        actions
                .andExpect(status().isCreated())
                .andExpect(header().string("Location", is(startsWith("/v11/members/"))))
                .andDo(document(       // (7)
                        "post-member",     // (7-1)
                        getRequestPreProcessor(),      // (7-2)
                        getResponsePreProcessor(),     // (7-3)
                        requestFields(             // (7-4)
                                List.of(
                                        fieldWithPath("email").type(JsonFieldType.STRING).description("이메일"), // (7-5)
                                        fieldWithPath("name").type(JsonFieldType.STRING).description("이름"),
                                        fieldWithPath("phone").type(JsonFieldType.STRING).description("휴대폰 번호")
                                )
                        ),
                        responseHeaders(        // (7-6)
                                headerWithName(HttpHeaders.LOCATION).description("Location header. 등록된 리소스의 URI")
                        )
                ));
    }
}

[코드 3-214] MemberController 클래스의 postMember() 핸들러 메서드에 대한 API 스펙 정보 추가

 

코드 3-214는 MemberController 클래스의 postMember() 핸들러 메서드에 대한 API 스펙 정보를 추가하기 위한 테스트 케이스입니다.

코드 길이가 꽤 길지만 앞에서 살펴본 ‘API 문서 생성을 위한 테스트 케이스의 기본 구조’에 구체적인 로직들이 조금 추가되었습니다.

1. MemberController 클래스의 코드를 확인해 보면 MemberService 클래스와 MemberMapper를 핸들러 메서드 안에서 사용하고 있습니다.또한 MemberService 객체를 통해 createMember() 메서드를 호출함으로써 실제 비즈니스 로직을 수행하고 데이터 액세스 계층의 코드까지 호출할 것입니다.따라서 MemberController가 MemberService와 MemberMapper의 메서드를 호출하지 않도록 관계를 단절시킬 필요가 있습니다.두 Mock 객체는 테스트 케이스에서 가짜 메서드를 호출하는 데 사용됩니다(Stubbing).
2. MemberController가 의존하는 객체와의 관계를 단절하기 위해 (1)과 (2)에서 MemberService와 MemberMapper의 Mock Bean을 주입받습니다.
3. 우리에게 필요한 핵심 관심사는 MemberController가 요청을 잘 전달받고, 응답을 잘 전송하며 요청과 응답이 정상적으로 수행되면 API 문서 스펙 정보를 잘 읽어 들여서 적절한 문서를 잘 생성하느냐 하는 것입니다.
4. 즉, 코드 3-214의 테스트 케이스가 MemberController의 postMember() 핸들러 메서드에 요청을 전송하면 MemberMapper를 이용해 MemberDto.Post 객체와 Member 객체 간의 실제 매핑 작업을 진행합니다.
5. (3)은 postMember() 핸들러 메서드에 전송하는 request body입니다.
6. (4), (5)는 여러분들이 Mockito 챕터에서 학습했던 내용입니다. MemberController의 postMember()에서 의존하는 객체의 메서드 호출을 (1)과 (2)에서 주입받은 Mock 객체를 사용해서 Stubbing하고 있습니다.
7. (6)은 Controller 슬라이스 테스트 챕터에서 학습했던 내용입니다. MockMvc의 perform() 메서드로 POST 요청을 전송하고 있습니다.

많이 돌아왔지만 (7)의 document(…) 메서드가 API 문서를 생성하기 위해서 알아야 될 내용입니다.

1. (7)의 document(…) 메서드는 API 스펙 정보를 전달받아서 실질적인 문서화 작업을 수행하는 RestDocumentationResultHandler 클래스에서 가장 핵심 기능을 하는 메서드입니다.
   1. document() 메서드의 첫 번째 파라미터인 (7-1)은 API 문서 스니펫의 식별자 역할을 하며, (7-1)에서 “post-member”로 지정했기 때문에 문서 스니펫은 post-member 디렉토리 하위에 생성됩니다.
   2. (7-2)와 (7-3)은 문서 스니펫을 생성하기 전에 request와 response에 해당하는 문서 영역을 전처리하는 역할을 하는데 [코드 3-215]와 같이 공통화한 후, 모든 테스트 케이스에서 재사용할 수 있도록 했습니다.

package com.springboot.util;

import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.*;

public interface ApiDocumentUtils {
   static OperationRequestPreprocessor getRequestPreProcessor() {
       return preprocessRequest(prettyPrint());
    }

    static OperationResponsePreprocessor getResponsePreProcessor() {
        return preprocessResponse(prettyPrint());
    }
}

[코드 3-215] ApiDocumentUtils 인터페이스

 

• preprocessRequest(prettyPrint())는 문서에 표시되는 JSON 포맷의 request body를 예쁘게 표현해 줍니다.
• preprocessResponse(prettyPrint())는 문서에 표시되는 JSON 포맷의 response body를 예쁘게 표현해 줍니다.

c. (7-4)의 requestFields(…)는 문서로 표현될 request body를 의미하며, 파라미터로 전달되는 List<FieldDescriptor>의 원소인 FieldDescriptor 객체가 request body에 포함된 데이터를 표현합니다.

d. (7-5)는 request body를 JSON 포맷으로 표현했을 때, 하나의 프로퍼티를 의미하는 FieldDescriptor입니다. type(JsonFieldType.STRING)은 JSON 프로퍼티의 값이 문자열임을 의미합니다.

e. (7-6)의 responseHeaders(…)는 문서로 표현될 response header를 의미하며, 파라미터로 전달되는 HeaderDescriptor 객체가 response header를 표현합니다.

• HttpHeaders.LOCATION : HTTP response의 Location header를 의미합니다.

드디어 MemberController의 postMember() 핸들러 메서드에 대한 API 스펙 정보가 테스트 케이스에 포함되었습니다.

이제 테스트 케이스를 실행하고, 실행 결과가 “passed”이면 우리가 작성한 API 스펙 정보를 기반으로 문서 스니펫이 만들어질 것입니다.

[그림 3-85] 테스트 케이스 실행 후, 생성된 문서 스니펫

 

테스트 케이스 실행 후, [그림 3-85]와 같이 문서 스니펫이 생성되었습니다.

 

[그림 3-86] http-request.adoc 문서 스니펫 내용 및 문서로 렌더링 된 모습

 

[그림 3-86]은 생성된 문서 스니펫 중에서 http-request.adoc 파일을 오픈한 모습입니다.

왼쪽은 http-request.adoc에 작성된 내용이며, 오른쪽은 Asciidoc 형태로 작성된 내용이 문서로 렌더링 된 모습입니다.

Asciidoc에 대해서는 뒤에서 학습하게 됩니다. ✔ MemberController의 patchMember() 핸들러 메서드에 대한 API 스펙 정보 추가

 

이번에는 MemberController의 patchMember() 핸들러 메서드에 대한 API 스펙 정보를 테스트 케이스에 추가해 보겠습니다.

package com.springboot.restdocs.member;

import com.springboot.member.controller.MemberController;
import com.springboot.member.dto.MemberDto;
import com.springboot.member.entity.Member;
import com.springboot.member.mapper.MemberMapper;
import com.springboot.member.service.MemberService;
import com.springboot.stamp.Stamp;
import com.google.gson.Gson;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
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.boot.test.mock.mockito.MockBean;
import org.springframework.data.jpa.mapping.JpaMetamodelMappingContext;
import org.springframework.http.MediaType;
import org.springframework.restdocs.payload.JsonFieldType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import java.util.List;

import static com.springboot.util.ApiDocumentUtils.getRequestPreProcessor;
import static com.springboot.util.ApiDocumentUtils.getResponsePreProcessor;
import static org.mockito.BDDMockito.given;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private MemberService memberService;

    @MockBean
    private MemberMapper mapper;

    @Autowired
    private Gson gson;

    ...
    ...

    @Test
    public void patchMemberTest() throws Exception {
        // given
        long memberId = 1L;
        MemberDto.Patch patch = new MemberDto.Patch(memberId, "홍길동", "010-1111-1111", Member.MemberStatus.MEMBER_ACTIVE);
        String content = gson.toJson(patch);

        MemberDto.Response responseDto =
                new MemberDto.Response(1L,
                        "hgd@gmail.com",
                        "홍길동",
                        "010-1111-1111",
                        Member.MemberStatus.MEMBER_ACTIVE,
                        new Stamp());

        // willReturn()이 최소한 null은 아니어야 한다.
        given(mapper.memberPatchToMember(Mockito.any(MemberDto.Patch.class))).willReturn(new Member());

        given(memberService.updateMember(Mockito.any(Member.class))).willReturn(new Member());

        given(mapper.memberToMemberResponse(Mockito.any(Member.class))).willReturn(responseDto);

        // when
        ResultActions actions =
                mockMvc.perform(
                            patch("/v11/members/{member-id}", memberId)
                                .accept(MediaType.APPLICATION_JSON)
                                .contentType(MediaType.APPLICATION_JSON)
                                .content(content)
                );

        // then
        actions
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.data.memberId").value(patch.getMemberId()))
                .andExpect(jsonPath("$.data.name").value(patch.getName()))
                .andExpect(jsonPath("$.data.phone").value(patch.getPhone()))
                .andExpect(jsonPath("$.data.memberStatus").value(patch.getMemberStatus().getStatus()))
                .andDo(document("patch-member",
                        getRequestPreProcessor(),
                        getResponsePreProcessor(),
                        pathParameters(              // (1)
                                parameterWithName("member-id").description("회원 식별자")
                        ),
                        requestFields(
                                List.of(
                                        fieldWithPath("memberId").type(JsonFieldType.NUMBER).description("회원 식별자").ignored(),    // (2)
                                        fieldWithPath("name").type(JsonFieldType.STRING).description("이름").optional(),    // (3)
                                        fieldWithPath("phone").type(JsonFieldType.STRING).description("휴대폰 번호").optional(),
                                        fieldWithPath("memberStatus").type(JsonFieldType.STRING).description("회원 상태: MEMBER_ACTIVE / MEMBER_SLEEP / MEMBER_QUIT").optional()
                                )
                        ),
                        responseFields(      // (4)
                                List.of(
                                        fieldWithPath("data").type(JsonFieldType.OBJECT).description("결과 데이터"),
                                        fieldWithPath("data.memberId").type(JsonFieldType.NUMBER).description("회원 식별자"),           // (5)
                                        fieldWithPath("data.email").type(JsonFieldType.STRING).description("이메일"),
                                        fieldWithPath("data.name").type(JsonFieldType.STRING).description("이름"),
                                        fieldWithPath("data.phone").type(JsonFieldType.STRING).description("휴대폰 번호"),
                                        fieldWithPath("data.memberStatus").type(JsonFieldType.STRING).description("회원 상태: 활동중 / 휴면 상태 / 탈퇴 상태"),
                                        fieldWithPath("data.stamp").type(JsonFieldType.NUMBER).description("스탬프 갯수")
                                )
                        )
                ));
    }
}

[코드 3-216] MemberController 클래스의 patchMember() 핸들러 메서드에 대한 API 스펙 정보 추가

 

코드 3-216에서는 MemberController 클래스의 patchMember() 핸들러 메서드에 대한 API 스펙 정보를 추가했습니다.

postMember() 핸들러 메서드에 대한 테스트 케이스와 크게 달라진 건 없지만 몇 가지 추가된 부분이 있습니다.

1. (1)에서는 API 스펙 정보 중에서 URL의 path variable의 정보를 추가했습니다. MemberController의 patchMember()와 getMember()는 “/v11/members/{member-id}”와 같은 요청 URL에 path variable이 있는 사실은 우리가 이미 잘 알고 있는 내용입니다.
2. memberId의 경우, path variable 정보로 memberId를 전달받기 때문에 MemberDto.Patch DTO 클래스에서 request body에 매핑되지 않는 정보입니다.

따라서 (2)와 같이 ignored()를 추가해서 API 스펙 정보에서 제외했습니다.

1. 회원 정보는 모든 정보를 다 수정해야만 하는 것이 아니라 선택적으로 수정할 수 있어야 합니다. 즉, 회원 이름, 휴대폰 번호, 회원 상태 중에서 수정하고 싶은 것만 선택적으로 수정할 수 있어야 하기 때문에 (3)과 같이 optional()을 추가해서 API 스펙 정보에서 필수가 아닌 선택 정보로 설정합니다.
2. (4)의 responseFields(…)는 문서로 표현될 response body를 의미하며, 파라미터로 전달되는 List<FieldDescriptor>의 원소인 FieldDescriptor 객체가 response body에 포함된 데이터를 표현합니다.

• JsonFieldType.OBJECT : JSON 포맷으로 표현된 프로퍼티의 값이 객체임을 의미합니다.
• JsonFieldType.NUMBER : JSON 포맷으로 표현된 프로퍼티의 값이 int나 long 같은 Number 임을 의미합니다.

1. 1. (5)에서 fieldWithPath("data.memberId")의 data.memberId 는 data 프로퍼티의 하위 프로퍼티를 의미합니다.

{
    "data": {
        "memberId": 1,             // data.memberId
        "email": "hgd@gmail.com",
        "name": "홍길동1",
        "phone": "010-1111-1111",
        "memberStatus": "활동중",
        "stamp": 0
    }
}

 

지금까지 Controller의 테스트 케이스에 API 스펙 정보를 추가해서 API 문서 스니펫을 생성해 보았습니다.

이어지는 챕터에서는 우리가 생성한 API 문서 스니펫을 하나로 모아서 실제로 외부에 공개할 수 있는 API 문서를 만들어 보겠습니다.