[Spring Boot] Spring Rest Docs 사용하기 - GET

Spring Rest Docs는 REST API를 문서화하기 위해 사용하는 기술입니다. Spring Rest Docs는 다음의 기능을 제공합니다.

 

1. Test Code를 기반으로 Test 통과 시 REST API 문서를 생성해준다.
2. Test Code의 메서드를 사용하여 문서를 수정 및 보안할 수 있다.

따라서 Spring Rest Docs를 사용하면 Controller의 코드가 변하더라도 Test Code에 적용하기만 한다면 일일이 모든 문서를 수정할 필요가 없습니다.

 

🚩 Spring Rest Docs 설치 및 적용에 대해서는 언급하지 않겠습니다. (Spring Rest Docs Starter)

 

Spring에서 REST API를 테스트하기 위해서는 Controller 마다 다음을 초기화하여야 합니다.

 

• API 테스트를 위한 mockMvc
• request parameter를 넘겨줄 objectMapper
• persist()를 위한 EntityManager

따라서 ApiDocumentationTest라는 이름의 클래스를 상속받도록 하여 코드를 관리하겠습니다. ApiDocumentationTest 코드는 다음과 같습니다.

 

@RunWith(SpringRunner.class)
@SpringBootTest
public abstract class ApiDocumentationTest {

    @Rule
    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

    protected MockMvc mockMvc;

    @Autowired
    protected ObjectMapper objectMapper;

    @Autowired
    protected WebApplicationContext context;

    @Autowired
    protected EntityManager em;

    @Before
    public void setUp() {
        mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();
    }
}

 

ObjectMapper, EntityManager는 @Autowired를 사용하여 초기화를 합니다. mockMvc의 경우에 @Before를 사용하여 테스트 실행 전마다 초기화해주도록 하였습니다.

 

REST API 테스트에 필요한 설정이 끝났으므로 GET을 사용하여 Member를 조회하는 코드를 알아보겠습니다. 테이블은 다음을 참고해주시기 바랍니다. 테이블 설계

 

given, when, then의 순서로 코드를 알아보겠습니다. 먼저 given입니다.

 

//given
Address address = new Address("서울", "테스트", "123-4");
Member member = Member.createMember("박성수", "010-2356-5432", address);
em.persist(member);

 

Member 생성 시에는 name, phone, address가 필요합니다. 이때, Address는 value type이므로 new Address를 사용하여 생성시켜주고, 나머지 정보는 임의로 채워줍니다. 모든 정보가 채워졌다면 persist를 사용하여 생성된 member를 저장해줍니다.

 

다음은 when의 코드입니다. Test를 할 API는 Member의 Id를 사용하여 조회합니다. 따라서 "/api/v1/member/{id}"의 uri를 사용합니다.

 

//when
ResultActions result = mockMvc.perform(get("/api/v1/member/" + member.getId())
        .accept(MediaType.APPLICATION_JSON)
        .characterEncoding("UTF-8"));

 

mockMvc의 perform을 사용하여 어떤 방식을 사용할지 GET, POST, PUT, DELETE와 어떤 uri를 사용할 것인지를 설정해줍니다. accept는 클라이언트가 이해할 수 있는 콘텐츠 타입이 무엇인지 설정하는 것이고, characterEncoding은 문자 인코딩 방식을 설정하는 것입니다.

 

//then
result.andExpect(status().isOk())
        .andExpect(jsonPath("$.name").value(member.getName()))
        .andDo(document("GET-member",
               preprocessRequest(prettyPrint()),
               preprocessResponse(prettyPrint())));

 

위의 코드는 mockMvc를 통해 반환 결과의 status가 isOk인지 확인합니다. 그 후에 andExpect를 통해서 반환받은 json 데이터의 name field가 given에서 선언한 member의 이름과 같은지 확인합니다. 여기까지 끝났다면 andDo를 통해서 문서를 생성해줍니다. prettyPrint를 사용하지 않으면 request와 response가 1줄로 출력됩니다.

 

결과로 나온 .adoc 파일을 통해 문서를 생성하면 다음 그림과 같은 결과를 얻을 수 있습니다. (🧨 다음의 결과는 테스트의 일부입니다)

 

GET 문서 일부