RestAssured + RestDocs 문서화

nuyh99·2023년 8월 31일

프로젝트-요즘카페

목록 보기

7/9

배경

프론트엔드와 노션의 API 명세를 통해 협업하고 있었습니다.
어느날 백엔드측에서 API를 수정하고 노션의 명세를 최신화하지 않았습니다.

그 결과…
프론트엔드 극대노

따라서 신뢰도 있는 API 문서화가 필요했습니다.

Swagger
RestDocs
Springdoc

위의 선택지들이 있었고, 저희는 2번을 선택하기로 했습니다.
이유는 테스트 코드가 아닌 프로덕션 코드에 어노테이션을 붙이기 싫었기 때문입니다.

하지만 RestDocs로 만든 adoc, AsciiDocter로 만든 html 파일은 정말 못생겼습니다.

Swagger UI 등의 예쁜 문서화를 위해서는 OAS 규격을 따르는 yaml 파일이 필요했고, 저희는 RestDocs-Api-Spec 이라는 오픈 소스를 사용하기로 결정했습니다.

지금부터 간단하게 문서화를 시작해보겠습니다!!
예시 환경은 JDK17, Spring Boot 3.1.2 버전입니다.

문서화할 API

@PostMapping("/members")
public ResponseEntity<MemberResponse> create(@RequestBody final MemberRequest memberRequest) {
    MemberResponse saved = memberService.save(memberRequest);
    
    return ResponseEntity.ok(saved);
}

단순히 Member 엔티티를 생성하고 그 결과를 응답하는 API 입니다.

Request

단순히 바디에 name을 보냅니다.

Response

생성된 자원을 응답합니다.

RestAssured Test

@Test
@DisplayName("Member 생성 테스트")
void save() {
    MemberRequest request = new MemberRequest("연어");

    given().log().all()
            .contentType(ContentType.JSON)
            .body(request)
            .when()
            .post("/members")
            .then().log().all()
            .statusCode(200);
}

위와 같이 간단한 테스트를 작성했습니다.

RestDocs + OAS 적용

Spring REST Docs와 공식 깃허브를 보면서 따라해보겠습니다.

plugins {
    id 'com.epages.restdocs-api-spec' version '0.18.2'
}

우선 build.gradle의 플러그인 목록에 추가합니다.

testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.2'
testImplementation 'com.epages:restdocs-api-spec-restassured:0.18.2'
testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'

저희는 RestAssured로 테스트를 작성할 것이므로 위의 의존성을 추가합니다.
RestAssured를 쓰는데 MockMvc는 왜 추가하냐구요?
저게 없으면 나중에 문서화를 하기 위한 RestAssuredRestDocumentationWrapper 클래스를 사용할 수가 없습니다.

만약 MockMvc를 사용한다면

testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.2'
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

이런 식으로 변경합니다.

openapi3 {
    server = 'https://localhost:8080'
    title = '간단한 API'
    description = '회원 저장 API 입니다.'
    version = '0.1.0'
    format = 'yaml'
}

그리고 위처럼 openapi3 라는 작업을 추가합니다.
./gradlew openapi3를 통해 문서화를 하기 위함입니다.

tasks.named('test') {
    outputs.dir file('build/generated-snippets')
    useJUnitPlatform()
}

마지막으로 기존의 test 작업에 위와 같이 outputs.dir을 추가해줍니다.
해당 디렉토리에 adoc 파일들을 생성한다는 뜻입니다.

이제 기존의 RestAssured 테스트를 고쳐봅시다.

@ExtendWith(RestDocumentationExtension.class)
class MemberControllerTest{

RestDocs를 사용해야 하므로 @ExtendWith를 붙여줍니다.

private RequestSpecification spec;

@BeforeEach
void setUp(RestDocumentationContextProvider provider) {
    this.spec = new RequestSpecBuilder().addFilter(documentationConfiguration(provider))
            .build();
    RestAssured.port = port;
}

필드에 RequestSpecification을 참조해주고, @BeforeEach에서 provider를 주입 받아서 스펙을 생성해줍니다.
코드를 보면 아시겠지만, RestDocs는 필터를 사용해서 문서화를 하는 방식으로 동작합니다.

@Test
@DisplayName("Member 생성 테스트")
void save() {
    MemberRequest request = new MemberRequest("연어");

    given(spec).log().all()
            .filter(RestAssuredRestDocumentationWrapper.document(
                    "멤버 저장 API"
            ))
            .contentType(ContentType.JSON)
            .body(request)
            .when()
            .post("/members")
            .then().log().all()
            .statusCode(200);
}

위와 같이 기존 테스트에 filter() 항목을 추가해주고 돌리면 adoc 파일로 만들어지게 됩니다.
요청 파라미터, 응답 파라미터에 대한 설명도 추가해볼까요??

@Test
@DisplayName("Member 생성 테스트")
void save() {
    MemberRequest request = new MemberRequest("연어");

    given(spec).log().all()
            .filter(document(
                    "멤버 저장 API",
                    requestFields(
                            fieldWithPath("name").description("이름")),
                    responseFields(
                            fieldWithPath("id").description("회원 PK"),
                            fieldWithPath("name").description("이름")
                    )
            ))
            .contentType(ContentType.JSON)
            .body(request)
            .when()
            .post("/members")
            .then().log().all()
            .statusCode(200);
}