API 문서화와 Spring Rest Docs 사용기

bagt13·2022년 8월 7일

Spring

목록 보기

3/12

클라이언트가 REST API 애플리케이션에 요청을 전송하기 위해서 알아야 되는
요청 정보(요청 URI, request body, query parameter 등)를 정리하여 문서화 하는 것

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

API 문서는 직접 수기로 작성할 수도 있지만, 일반적으로 애플리케이션 빌드를 통해 API 문서를 자동 생성하는 경우가 많다.

Swagger의 장점 : Postman처럼 API 요청 툴로써의 기능을 사용할 수 있다

Swagger의 단점 : 꽤나 많은 애노테이션들이 애플리케이션 코드에 추가되어야 한다

Spring Rest Docs는 Swagger와 달리, 애플리케이션 기능 구현과 관련된 코드에는
API 문서 생성을 위한 애노테이션 같은 정보가 추가되지 않는다.

대신, Controller 테스트 코드가 선행되어야 하며, Controller 테스트 클래스에 API 문서를 위한 정보가 추가된다.

Spring Rest Docs의 장점 : Controller에서 구현한 request/response Body, Query Parmeter 등의 정보 중, 하나라도 일치하지 않으면 테스트에 실패하면서 API 문서가 정상적으로 생성이 되지 않는다.

테스트에 성공해야만 API 문서 생성
=> Controller에 정의되어 있는 Request Body나 Response Body 등의 API 스펙 정보와 일치하는 API 문서가 만들어진다는 것이다.

따라서 API 스펙 정보와 API 문서 내의 정보의 불일치로 인해 발생하는 문제를 방지해준다.

Spring Rest Docs의 단점 : 테스트 케이스를 일일이 작성해야 한다.

개발 시에 테스트 케이스 작성은 필수이므로, 딱히 단점이 아니라고 생각할 수도 있다.
하지만, 개발 도중에 API가 수시로 변경되는 상황에서는 변경사항에 대해 테스트 코드까지 일일이 수정하는 작업은 번거로울 수 있으므로, 이러한 상황에선 Swagger를 사용하는 편이 더 적합하다고 볼 수 있다.

그밖에도 GitBook, Postman 등으로도 작성할 수 있지만, 위의 두 방식이 가장 많이 사용되고 권장된다.

먼저 대략적인 생성 과정은 이러하다.

테스트 코드 작성 -> test 태스크(task) 실행 -> API 문서 스니핏(.doc 파일) 생성 -> API 문서 생성 -> API 문서를 HTML로 변환

1. build.gradle 설정

@WebMvcTest : @SpringBootTest 애노테이션은 보통 controller부터 DB까지 테스트하는 통합 테스트에서 사용하며, 가벼운 controller 슬라이스 테스트를 할때는 이 애노테이션을 사용할 수 있다.

@MockBean(JpaMetamodelMappingContext.class)

Spring 컨테이너를 요구하는 테스트는 가장 기본이되는 Application 클래스가 항상 로드되는데, 아래와 같이 @EnableJpaAuditing이 해당 클래스에 등록되어 있어 모든 테스트들이 항상 JPA 관련 Bean들을 필요로 하게 된다.

@SprignBootTest를 사용할 때는 전체 context를 로드하고 JPA를 포함한 모든 Bean을 주입받기 때문에 에러가 발생하지 않지만, @WebMvcTest같은 슬라이스 테스트는 JPA 관련 Bean들을 로드하지 않기 때문에 에러가 발생한다.

따라서, 이 애노테이션을 사용해 Mock 객체로 JPA 관련 Bean 들을 주입해준 것이다.

나머지 내용들은 일반적인 controller 테스트 코드와 크게 다르지 않으며, 마지막에 검증하는 부분에서 API 문서화 관련 코드를 추가한다.

document() 메서드 내부에 구체적인 스펙 내용을 명시하는 작업이 수행된다.
requestFields와 responseFields 내부에 requestBody/responseBody의 각 필드의 내용을 기재한다.
이때, 필드의 개수와 이름은 실제로 진행된 요청과 응답 스펙과 일치해야 한다.