[Rest Docs]Test 없는 API 문서는 시한폭탄

개발자로 일하다 보면 코드를 작성하고 API를 설계하는 것만큼이나 문서화하는 과정이 중요하다는 걸 깨닫게 되는데 문서화는 단순히 기록하는 것이 아니라 팀원이나 다른 개발자와의 소통을 원활하게 하는 핵심 도구로 작용합니다.

그러나 문서를 작성하는 과정에서 실수가 발생할 수 있으며 이를 제대로 검증하지 않으면 작은 오류가 큰 오해로 이어질 수 있기 때문에 이 글에서는 두 가지 문서화 방식을 비교하며 검증 과정이 왜 필요한지 살펴보겠습니다.

1. 검증 없이 기록만 남기는 문서화

아래는 검증 없이 API의 요청과 응답 형식만을 문서화한 코드입니다.

public RestDocumentationResultHandler getTest() {
    return document("test",
        requestParameters(
            parameterWithName("id").description("주문 ID"),
            parameterWithName("item").description("상품 ID")),
        responseFields(
            fieldWithPath("data.list").type(JsonFieldType.ARRAY).description("주문서 배열"),
            fieldWithPath("data.list[].id").type(JsonFieldType.NUMBER).description("주문서 ID"),
            fieldWithPath("data.list[].item").type(JsonFieldType.STRING).description("상품 이름"),
            fieldWithPath("data.list[].url").type(JsonFieldType.STRING).description("상품 링크"),
            fieldWithPath("data.count").type(JsonFieldType.NUMBER).description("주문서 개수"))
    );
}

이 코드는 요청 파라미터와 응답 필드를 깔끔하게 정리하고 각 항목에 대한 설명을 제공하지만,치명적인 문제점은 검증이 전혀 이루어지지 않는다는 점입니다.

예를 들어, url 대신 실수로 link라고 적었거나 Controller의 스펙이 변경되었지만 문서화 코드를 수정하지 않았다면 문서와 실제 API 응답이 불일치하여 신뢰할 수 없는 문서가 됩니다.

2. 검증을 포함한 문서화

아래는 API 요청과 응답을 검증한 후 문서화하는 코드입니다.

public void getTest() throws Exception {
    List<Voucher> list = List.of(
        Voucher.builder().id(1L).item("Item1").url("link1").build(),
        Voucher.builder().id(2L).item("Item2").url("link2").build()
    );

    when(service.getList(any())).thenReturn(list);

    mockMvc.perform(get("/v1/voucher").param("id", "1,2").param("item", "Item1,Item2")
                        .contentType(MediaType.APPLICATION_JSON)) 
        .andExpect(status().isOk()) 
        .andExpect(jsonPath("$.data.list[0].id").value("1")) 
        .andExpect(jsonPath("$.data.list[0].item").value("Item1")) 
        .andExpect(jsonPath("$.data.list[1].id").value("2")) 
        .andExpect(jsonPath("$.data.count").value("2"))
        .andDo(document("test",
            requestParameters(
                parameterWithName("id").description("주문 ID"),
                parameterWithName("item").description("상품 ID")),
            responseFields(
                fieldWithPath("data.list").type(JsonFieldType.ARRAY).description("주문서 배열"),
                fieldWithPath("data.list[].id").type(JsonFieldType.NUMBER).description("주문서 ID"),
                fieldWithPath("data.list[].item").type(JsonFieldType.STRING).description("상품 이름"),
                fieldWithPath("data.list[].url").type(JsonFieldType.STRING).description("링크"),
                fieldWithPath("data.count").type(JsonFieldType.NUMBER).description("주문서 개수"))
    ));
}

이 코드에서 중요한 부분은 perform과 andExpect입니다.

 

• perform : API 요청을 실행하는 역할을 합니다.
• andExpect : 응답을 검증하는 역할을 합니다.
  • status().isOk() : API 호출이 성공했는지 확인합니다.
  • jsonPath(...).value(...) : 응답 데이터의 특정 값이 기대한 값과 일치하는지 확인합니다.

검증된 API 문서는 필드 이름이나 응답 구조가 변경되었을 경우 테스트가 실패하게 되며 이로 인해 잘못된 문서가 배포되는 것을 방지할 수 있습니다.

3. 결론

검증 없이 문서화하면 개발 속도는 빠를 수 있지만 필드 이름이나 응답 구조가 변경될 경우 이를 감지하기 어렵기 때문에 결과적으로 문서의 신뢰성이 떨어지고 협업 과정에서 불필요한 혼선이 발생할 수 있습니다.

반면 검증을 포함한 문서화 방식은 API 문서가 실제 응답과 일치하도록 보장하며 만약 변경이 생기면 테스트가 실패하여 개발자가 즉시 수정할 수 있도록 돕습니다.

특히 외부 개발자와 협업할 때 이러한 차이는 소통의 질과 신뢰도를 크게 좌우할 수 있습니다.

 

API 문서는 단순한 기록이 아니라 신뢰할 수 있는 정보를 제공하는 수단이어야 하기 때문에 문서화 과정에서 검증을 포함하는 것은 필수 사항이라고 생각합니다.