[Spring] Swagger vs RestDocs

서론

• REST docs 와 Swagger의 장점과 단점
  • Spring REST docs
    • 프로덕션 코드에 별다른 영향을주지 않는다.
    • 테스트 기반으로 작성되며, Snippet이 올바르지 않을경우 테스트가 실패한다. 테스트를 강제하며, 테스트가 검증되면 작성되는 문서 또한 신뢰할 수 있다는 장점 존재
    • [ Spring Rest Docs vs Swagger ]
                              Spring Rest Docs                                                                      Swagger

    장점	서비스 코드에 영향을 주지않는다.	간편하게 적용이 가능하다.
    	테스트가 성공해야 문서를 만들어준다.	API 테스트가 가능하다.
    단점	적용하기 어렵다.	서비스 코드에서 어노테이션을 추가해야한다.
    	테스트 코드 작성을 필수로 요구한다.	문서만으로 연동 시스템을 만들기 어렵다.

    • 이전 회의때 언급되었던 TDD 기반으로 진행되는 프로젝트에 적합하지 않을까 판단하였음
    • 전반적인 흐름구조
      • Spring MVC Test, Spring WebFlux WebTestClient, RestAssured 등으로 테스트코드 작성
      • 해당 테스트 코드에 대한 Snippet 자동생성
      • 사용자가 미리 작성한 템플릿 문서 + Snippet을 결합해 최종적인 API 문서 제작

 

• API docs
  • API 문서의 목적은 개발하는 스펙을 정의하는 것
• Swagger
  • API 동작을 테스트하는 용도로 더 특화되어 있다.
  • 위 장단점에 나와 있는 것처럼 간편한 사용법과, API 구동 테스트가 가능하지만, 서비스 코드에 어노테이션이 추가되기에 지저분해 보일 수 있다.
  • 간편하게 API 동작을 확인하고 싶을때는 Swagger를 사용하는 게 더 적합하다.
• Spring REST docs
  • 우아한 형제들 기술블로그 , 여러가지 구글링을 통해 찾아봤을 때 Spring에 어울리는 API docs로 REST docs가 많이 보였다.
  • 테스트 성공 기반으로 작성되기에, 테스트 코드를 작성하며 개발을 진행한다 했을땐 REST docs가 더 적합하다.
• 결론
  • 그렇기에 상황에 따라 선택하는 것이 좋다고 판단되었다. 만약, 테스트 코드를 하나하나 작성하며 진행한다고 했을땐, 테스트 코드 기반으로 성공하였을때 문서를 만들어주는 REST docs
  • API 구동 동작을 확인하고, 간편하게 API 문서 제작을 하고 싶을땐 Swagger