240129 TIL - RestDocs

이번 프로젝트를 하면서 늦은감이 있지만 테스트코드를 작성하려고 한다. 테스트코드를 작성하면 CI에 테스트코드를 통과해야 merge와 배포를 할 수 있게 하는 기능을 사용할 수 있어 양질의 코드를 짤 수 있는 효용이 있다. 그리고 테스트코드를 기반으로 API문서를 생성해주는 RestDocs라는 툴을 사용하기로 했다. RestDocs와 Swagger가 비슷한 기능을 해주는 툴이라서 둘 중에 어떤것을 사용할지 의논해보았는데

Swagger는 자동으로 API를 스캔하고 문서화하는 데 중점을 두고 있고 이는 개발 초기 단계에서 API의 기본 구조를 빠르게 파악하고 공유하는 데 유용하다. 또 Swagger UI를 통해 API를 직접 테스트하고 시각화할 수 있다. 그러나 자동화된 문서화 방식으로 인해, API가 변경될 때마다 문서가 자동으로 업데이트되지만, 이는 문서의 정확성을 보장하기 어렵다.

반면에 REST Docs는 테스트 기반의 문서화 방식을 사용한다. 이는 API 테스트를 통과한 경우에만 문서가 생성되며, 이로 인해 문서의 정확성이 높아진다. 또한, 각 API가 어떻게 동작하는지, 어떤 입력을 받고 결과를 반환하는지에 대한 상세한 설명을 제공하므로, API의 사용자에게 더욱 명확한 가이드를 제공할 수 있다는 장점이 있다. 우리 팀에서는 문서의 정확성과 상세한 설명이 더 중요하다고 판단되어 RestDocs를 사용하기로 결정했다.

사용방법은 의존성을 추가해준 뒤 andDo(document()) 메서드로 문서화하고 필요한 필드 설명을 fieldWithPath() 메서드를 이용해 추가할 수 있다고 한다. 테스트코드를 짜는데 어려움을 겪었던 터라 이번에 테스트코드에 대해 확실히 감을 잡고 RestDocs로 하나하나 문서화되는 것을 보며 성취감을 느끼며 테스트코드를 작성할 수 있었으면 좋겠다.