[S3 U8] Spring MVC API 문서화

[S3 U8] Spring MVC API 문서화

학습목표

• API 문서화가 왜 필요한지 이해할 수 있다.
• Spring Rest Docs의 사용법을 이해할 수 있다.
• Spring Rest Docs와 Swagger의 차이점을 이해할 수 있다.
• Spring Rest Docs를 이용해서 API를 문서화 할 수 있다.
• 문서화된 API를 외부 사용자에게 제공할 수 있다.

API 문서화

• API 문서화 : 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야되는 요청 정보(요청 URL(또는 URI), request body, query parameter 등)을 문서로 잘 정리하는 것

API 사용을 위한 어떤 정보가 담겨있는 문서를 API 문서 또는 API 스펙(Specification)이라고 함

API 문서 생성의 자동화가 필요한 이유

• 애플리케이션 구현 단계 전/후로 문서작업을 해야하는 경우가 많음
• API 문서 마저도 수기로 직접 작성하는 것은 비효율적임.
• API문서는 기능 추가되거나 수정됨에 따라 빈번하게 수정되는데, 직접 수정하는 것은 수정사항 누락 등 오류를 발생할 가능성이 높음
• API 문서 자동화를 통해 작업 시간 단축 및 애플리케이션의 완성도 증대

Spring Rest Docs vs Swagger

기능/특징	Swagger	Spring Rest Docs
API 디자인	제공	미제공
API 모델링	제공	미제공
요청 및 응답 형식 정의	제공	미제공
문서화	제공	제공
문서화 방식	OpenAPI 사양 기반	실제 코드 기반
사용 방법	API 디자인, 빌드, 문서화, 테스트를 위한 도구 모음	Spring 프레임워크와 함께 사용하여 API 문서화
장점	모든 API 개발 단계를 제공	정확성과 일관성을 유지하는 API 문서화
단점	Spring 프레임워크와 통합이 제한적	API 디자인에 대한 제한적인 기능

---

Spring Rest Docs

Spring Rest Docs : REST Api 문서를 자동으로 생성해주는 Spring 하위 프로젝트

• Controller의 슬라이스 테스트를 통해 테스트가 통과되어야지만 API 문서가 정상적으로 작성됨
• 테스트를 중요하게 생각하는 개발자들에게 각광받는 기술 중 하나

Spring Rest Docs의 API 문서 생성 흐름

• 테스트 코드 작성
  • 슬라이스 테스트 코드 작성
    • Controller의 슬라이스 테스트 코드 작성
  • API 스펙 정보 코드 작성
    • Request Body, Response Body, Query Parameter 등 코드 작성
• Test 태스크(Task) 실행
  • 작성된 슬라이스 테스트 코드 실행
    • Gradle의 빌드 태스크(Task) wnd 하나인 test tesk 실행
    • 테스트 실행 결과 “Passed”면 다음 작업 진행, “Failed”이면 문제 해결 후 다시 테스트 진행
• API 문서 스니핏(.adoc 파일) 생성
  • 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 생성(.adoc 확장자)
• API 문서 생성
  • 생성된 API 문서 스니핏을 모아서 하나의 API 문서 생성
• API 문서를 HTML로 변환
  • 생성된 API 문서를 HTML파일로 변환
  • HTML 파일 자체로 공유할 수도 있고, URL로 접근하여 확인할 수 있음.

API 문서 생성을 위한 슬라이스 테스트 케이스 기본구조(MemberController)

import com.codestates.member.controller.MemberController;
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 문서 스펙 정보 추가
                 ));
    }
}