SEB_BE 58일차 - API 문서화2

subimm_·2022년 11월 16일

springMVC 백엔드 코드스테이츠

코드스테이츠

목록 보기

58/83

💡 오늘의 학습목표

Spring Rest Docs 적용
이메일 전송

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

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

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

(1) 에서는 @SpringBootTest 애너테이션 대신 @WebMvcTest 사용
@WebMvcTest 애너테이션은 Controller 테스트 전용 애너테이션
괄호 안에는 테스트 대상 Controller 클래스 지정
(2) JPA에서 사용하는 Bean 들을 Mock 객체로 주입해주는 설정
Spring Boot 기반 테스트는 항상 최상위 패키지 경로에 있는 xxxxxxApplication 클래스를 찾아서 실행
@EnableJpaAuditing 애너테이션 추가하면 JPA와 관련된 Bean을 필요로 하기 때문에 @WebMvcTest 애너테이션을 사용한 테스트의 경우 (2)와 같이 JpaMetamodelMappingContext를 Mock 객체로 주입해주어야 함.
(3) Spring Rest Docs에 대한 자동 구성을 위해 추가
(4) MockMvc 객체 주입 받음
(5) Controller 클래스가 의존하는 객체 (주로 서비스 클래스, Mapper) 의 의존성 제거 위해 애너테이션을 사용해서 Mock 객체 주입 받음.
(6) HTTP request에 필요한 request body나, query parameter, path variable 등의 데이터 추가
(7) (5)에서 주입 받은 Mock 객체가 동작하도록 Mockito에서 지원하는 given() 등의 메서드로 Stubbing 해준다.
(8) perform() 메서드로 request 전송
(9) response 검증
마지막으로 (10) 에서 테스트 수행 후 API문서를 자동 생성하기 위한 해당 Controller 핸들러 메서드의 API 스펙 정보를 document(...)에 추가
document(...) 메서드는 API 문서를 생성하기 위해 Spring Rest Docs 에서 지원하는 메서드
andDo(...) 메서드는 일반적인 동작을 정의하고자 할 때 사용

@WebMvcTest 는 Controller를 위한 슬라이스 테스트에 주로 사용

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

MemberContorller 테스트 케이스에 API 스펙 정보 추가
✔ MemberController의 postMember() 핸들러 메서드에 대한 API 스펙 정보 추가
MemberController 클래스의 코드에서 MemberService 클래스와 MemberMapper를 핸들러 메서드 안에서 사용하고 있다.
테스트 케이스가 postMember()핸들러 메서드에 요청 전송 시 MemberMapper를 이용해 MemberDto.Post객체와 Member 객체 간의 실제 매핑 작업 진행
또한 MemberService 객체를 통해서 createMember() 메서드를 호출하여 비즈니스 로직 수행 후 데이터 액세스 계층의 코드까지 호출 -> 관계 단절 필요 (1), (2)에서 MemberService와 MemberMapper의 Mock Bean 주입 받음 (테스트에서 가짜 메서드 호출 시 사용(Stubbing))
(3) postMember() 핸들러 메서드에 전송하는 request body
(4) postMember() 핸들러 메서드가 응답으로 전송하는 response body
(5), (6), (7) 은 postMember()에서 의존하는 객체의 메서드 호출을 Mock객체를 사용해서 Stubbing
(8) MockMvc의 perform() 메서드로 POST 요청 전송

(9) document(...) 메서드는 API 스펙 정보를 전달 받아서 실질적인 문서화 작업을 수행하는 메서드

document() 메서드의 첫번째 파라미터 (9-1) 은 API 문서 스니핏의 식별자 역할
지정한 이름으로 문서 스니핏은 post-member 디렉토리 하위에 생성됨.

(9-2),(9-3) 문서 스니핏 생성 전 request와 response에 해당하는 문서 영역을 전처리하는 역할, ( 공통화 한 후 모든 테스트 케이스에서 재사용 가능케 함)

JSON 포맷의 request, response body를 예쁘게 표현해 준다.

(9-4) requestFields(..) 문서로 표현될 request body를 의미 파라미터로 전달되는 List<FieldDescriptor>의 원소인 FieldDescriptor 객체가 바디에 포함된 데이터 표현

(9-5) request body 를 JSON 포맷으로 표현 시, 하나의 프로퍼티를 의미하는 FieldDescriptor , type(JsonFieldType.STRING) 은 프로퍼티의 값이 문자열을 의미

(9-6) response body 를 의미

✔ patchMember() 핸들러 메서드에 대한 API 스펙 정보 추가 (바뀐 부분)

(1) API 스펙 정보 중에서 URL의 path variable 의 정보를 추가함.
(2) memberId 의 경우, path variable 정보로 memberId를 전달 받기 때문에 MemberDto.patch DTO 클래스에서 request body에 매핑되지 않는 정보 -> (2) ignored() 추가하여 API스펙 정보에서 제외
(3) 회원 정보는 선택적으로 수정해야함. (3) optional() 을 추가하여 선택정보로 설정

📔 스니핏을 이용한 API 문서화

📖 API 문서 템플릿 생성을 위한 디렉토리 및 템플릿 문서 생성

src/docs/asciidoc 디렉토리 생성 후 비어있는 index.adoc 파일 생성

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

📖 템플릿 문서 내용 추가

(1) API 문서의 제목
(2) API 문서를 생성한 사람의 정보
(3) API 문서의 생성 날짜
(4) 테스트 케이스 실행을 통해 생성한 API 문서 스니핏을 사용하는 부분
include::{snippets}/스니핏 문서가 위치한 디렉토리/스니핏 문서파일명.adoc[]

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

Gradle 탭에서 :bootJar 또는 :build 실행
정상적으로 빌드 종료 후 src/main/resources/static/docs 디렉토리에 변환된 파일 생성됨.
애플리케이션 실행 후 http://localhost:8080/docs/index.html 접속