[TIL] API 문서화

🙌🏻 API Documentation 

 📍 API 문서 / API 스펙 / API 사양

 - API 사용을 위한 어떤 정보가 담겨 있는 문서

 - 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해 알아야 되는 요청 정보를 문서로 잘 정리하는 것

   → 요청정보 : 요청 URL(URI), Request Body, Query Parameter 등

 - 개발자가 API 정보를 직접 수기로 작성할 수도 있고 애플리케이션 빌드를 통해 자동 생성도 가능

---

📍API 문서화 방식

① Swagger

 - 애너테이션 기반의 API 문서화 방식

 - 애플리케이션 코드 안에 기능 구현과 관련된 애너테이션 추가됨

 - 가독성 및 유지 보수성이 떨어짐

 - API 문서와 API 코드 간 정보 불일치 문제가 발생할 수 있음

 - API 툴로써의 기능을 활용할 수 있음

② Spring Rest Docs

 - 테스트 코드 기반의 애너테이션

 - API 문서 생성을 위한 애너테이션과 같은 어떠한 정보도 추가되지 않음

 - 테스트 케이스 실행이 Passed여야 API 문서 생성됨

 - 테스트 케이스를 반드시 작성해야 함

 - API 툴로써의 기능은 제공하지 않음

---

📍 Spring Rest Docs의 API 문서 생성 흐름

① 테스트 코드 작성

 ▸ 슬라이스 테스트 코드 작성

  - Spring Rest Docs는 Controller의 슬라이스테스트와 밀접한 관련이 있음

  - Controller에 대한 슬라이스 테스트 코드를 먼저 작성함

 ▸ API 스펙 정보 코드 작성

  - Controller에 정의 되어 있는 API 스펙 정보(Request Body, Response Body, Query Parameter 등)을 코드로 작성

---

② test 태스크 실행

 ▸ 작성한 슬라이스 테스트 코드 실행

  - 하나의 테스트 클래스 or Gradle 빌드 태스크 중 하나인 test task를 실행 시켜서 API 문서 스니핏을 일괄 생성

 ▸  테스트 실행 결과 확인 

  - 실행 결과가 passed 이면 다음 작업 진행

  - 실행 결과가 failed 이면 문제를 해결하기 위한 테스트 케이스를 수정한 후 다시 테스트 진행

---

③ API 문서 스니핏(.adoc 파일) 생성

  - 실행 결과가 passed 이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니핏( .adoc )이 파일로 생성

 💡 스니핏 : Snippet

    - 일반적으로 코드의 일부 조각을 의미 ( or 문서의 일부 조각 )

    - 테스트 케이스 하나 당 하나의 스니핏이 생성됨

    - 여러 개의 스니핏을 모아서 하나의 API 문서 생성할 수 있음

    - .adoc 문서 스니핏을 생성해주는 Asciidoctor 필요

---

④ API 문서 생성

  - 생성된 API 문서 스니핏을 모아서 하나의 API 문서 생성

---

⑤ API 문서를 HTML로 변환

  - 생성된 API 문서를 HTML 파일로 변환

  - HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수도 있고 URL을 통해 해당 HTML에 접속해서 확인 가능

     - 즉 외부에 제공할 수도 있고 웹 브라우저에 접곡해서 API 문ㅁ서 확인 가능

---

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

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

@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean
    //테스트 대상 Controller 클래스가 의존하는 객체 입력
    
    @Test
    public void postMemberTest() throws Exception {
        //given
        //테스트 데이터
        //Mock 객체를 이용한 Stubbing
        
        //when
        ResultActions actions = mockMvc.perform( //request전송// )
        
        //then
        actions
            .andExpect( //response에 대한 기대 값 검증 // )
            .andDo(document( //API 문서 스펙 정보 추가 ));
    }
}

① @WebMvcTest(MemberController.class)

 - Controller를 테스트 하기 위한 전용 애너테이션

 - 애터네이션 괄호 안에는 테스트 대상 Controller 클래스를 지정해줌

---

② @MockBean(JpaMetamodelMappingContext.class)

 - JPA에서 사용하는 Bean들을 Mock 객체로 주입해주는 설정

---

③ @AutoConfigureRestDocs

 - Spring Rest Docs에 대한 자동 구성을 해줌

---

④ private MockMvc mockMvc

 - MockMvc 객체를 주입 받음

---

⑤ @MockBean

 - Controller 클래스가 의존하는 객체 (주로 Service, Mapper)의 의존성을 제거하기 위해 @MockBean에 Mock 객체 주입

---

⑥ given의 테스트 데이터

 - HTTP request에 필요한 Request Body나 Query Parameter, Path Variable 등의 데이터 추가

---

⑦ given의 Stubbing

 - MockBean을 통해 주입받은 Mock 객체가 동작하도록 given( ) 등의 메서드로 Stubbing 해줌

---

⑧ mockMvc.perform( request 전송 )

 - MockMvc의 perform( ) 메서드로 request 전송

---

⑨ .andExpect( response에 대한 기대 값 검증 )

 - 슬라이스 테스트와 동일하게 검증 진행

---

⑩ .andDo(document( API 문서 스펙 정보 추가 ))

 - andDo(...) 메서드는 andExpect( ) 처럼 어떤 검증 작업을 하는 것이 아니라 일반적인 동작을 정의하고자 할 때 사용

---

💡 SpringBootTest vs WebMvcTest

   ▪️ @SpringBootTest

   - @AutoConfigureMockMvc와 함께 사용되어 Controller를 테스트

   - 프로젝트에서 사용하는 전체 Bean을 ApplicationContext에 등록하여 사용함

   - 테스트 환경을 구성하는 것은 편리하지만 실행 속도가 상대적으로 느림

   - 사용 : 데이터베이스까지 요청 프로세스가 이어지는 통합 테스트에 주로 사용

   ▪️ @WebMvcTest

   - Controller 테스트에 필요한 Bean만 Application Context에 등록하기 때문에 실행 속도 상대적으로 빠름

   - 사용 : Controller를 위한 슬라이스 테스트에 주로 사용