보통 API 자동화 툴이라고 하면 swagger, REST API docs 가 자주 고려된다.
서치하다보니 추가로 restdocs-api-spec 이라는 라이브러리도 알게 되어 각각의 장단점을 함께 비교해보려고 한다.
Swagger
swagger 는 OpenAPI 사양을 사용하기 때문에, 표준화된 형식을 지원한다.
또한 우리의 프론트엔드 팀원들이 API 문서 페이지에서 직접 API 호출을 시도해볼 수 있는 대화형 인터페이스를 제공한다.
무엇보다 시작하기 쉽다. swagger 의존성만 있어도 API 문서를 만들어준다!
단점
가장 크고 자주 지적되는 단점은 프로덕션 코드에 swagger 코드가 침투한다는 것이다.
컨트롤러에 swagger 코드가 추가되어 가독성을 떨어뜨릴 수 있다는 단점이 있다.
Test 를 강제하지 않기 때문에 문서의 신뢰도를 높게 유지하기 어려운 문제가 있다.
Spring REST docs
가장 손꼽히는 장점은 테스트로부터 API 문서를 생성하므로 문서는 언제나 실제 코드와 함께 최신 상태라는 것이 보장된다.
integration 테스트를 작성해서, 테스트가 통과해야만 문서가 작성된다. 따라서 문서의 신뢰도가 높게 유지된다.
개발 리소스가 발생하기는 하지만, 테스트를 강제하기 때문에 유지보수에도 도움이 된다고 한다.
swagger 와는 달리 컨트롤러 코드에 어노테이션을 달지 않아도 된다. 소스 코드에 변경을 주지 않기 때문에 비즈니스 로직과 테스트케이스가 분리된다는 장점이 있다.
단점
ascii docs 를 써야 한다.... 테스트 코드가 추가될 때마다 ascii doc 에 적어야 한다.
또한 Swagger UI 와 다르기 때문에, 클라이언트 쪽에서 API 를 호출해볼 수 없다.
추가적으로 UI 가 swagger 에 비해서는 우아하지 않다. (예쁜 것도 중요하다.)
그러나 테스트 코드가 변경될 떄마다 직접 문서를 수정해야 하는 상황이 발생할 수 있다. (즉, 매우 귀찮다.)