Spring Rest Docs와 Open Api (Swagger)

Spring Rest Docs의 특징

Spring Rest Docs로 작성된 문서

Spring Rest Docs는 Test 기반으로 동작합니다. 테스트 코드에 추가함으로써 문서가 작성되며 Production코드에 영향을 미치지 않는다는게 큰 장접입니다. 테스트 기반이기 때문에 테스트가 수행되지 않으면 문서 또한 작성되지 않는다. 따라서 문제가 있는 경우엔 문서또한 작성되지 않는다는 장점(?)이 있다. 또한 문서 본연의 기능에 충실한다.

하지만 테스트 기반으로 설계된 서비스가 아니라면, 사용이 불가능합니다. 또한 추가적인 설정들을 적용하기가 쉽지 않다는 단점을 가지고 있다.

Swagger의 특징

Swagger로 작성된 페이지

Spring Rest Docs와 반대로 Open APi로 작성된 문서는 Swagger UI를 통해 실제 API를 테스트하는 기능을 제공한다.

Production 코드에 문서화와 관련된 코드가 추가된다는 점이 OpenApi의 단점이다. 가독성이 굉장히 떨어지고, 객체 지향의 관점에서도 컨트롤러에 문서화라는 역할이 추가되는 느낌이다.