Spring Rest Docs vs Swagger

[tco0427]

• Spring Rest Docs 와 비교하여 Swagger의 장단점은?
• Swagger와 비교하여 Spring Rest Docs의 장단점은?
• 어떤 것을 도입하고 싶은지? 그 이유는?

[tco0427]

우선 학습적인 측면을 제외하고 각각의 장단점을 비교해보자.

• Swagger
  • 장점
    • GET, DELETE 등 HTTP 메소드에 따라 구분(색을 통해)해주며 편리하게 사용할 수 있다.
    • API 문서화 이외에도 실제 API를 간단하게 테스트 하는 기능을 제공한다.
    • 프로젝트 코드에 설정을 통해서 굉장히 간단하게 API 문서를 얻을 수 있다. (Controller 등 여러 코드에 Swagger 관련 코드가 흩어져 있을 수도 있지만, 이러한 기능을 사용하지 않고, SwaggerConfig와 같이 Config 파일만 하나 두어 Swagger를 활용한다면 프로덕트 포크에 Swagger 코드라는 단점을 최대한 보완할 수 있다고 생각한다.)
  • 단점
    • 프로덕트 코드에 Swagger 설정과 관련된 코드가 포함되게 된다. (앞서 언급한 것과 같이 Swagger를 사용하지 않는다면 SwaggerConfig 파일만 제거하면 된다. (Swagger 관련 의존성이 하나의 파일에))
    • 프로덕트 코드와 동기화가 안될 수 있다. (직접 느껴보지는 못한 단점)
• Spring Rest Docs
  • 장점
    • 프로덕트 코드에 영향이 없다.
    • 테스트가 제대로 수행되지 않으면 문서가 작성되지 않는다는 장점이 있다.
  • 단점
    • 테스트를 작성해야하기 때문에 비용이 든다. (이 부분은 관점에 따라 다르다고 생각합니다. 테스트가 성공해야 문서 작성이 된다 라는 점을 장점으로 꼽은 것처럼 꼼꼼한 테스트 작성이 가능해지기 때문이다. 하지만 Swagger와 비교한다면 단점이 될 수 있다고 생각한다.)
    • 엔드포인트마다 수많은 코드를 추가해줘야한다. (그만큼 여러 메소드를 알아야 하기 때문에 제대로 사용하기 위해서는 학습해야 할 양도 많다고 생각된다.)

어제 짱구, 그린론과 이야기해보니 현재 AcceptanceTest 에서 사용하는 것과 같이 RestAssured를 통해서 Spring Rest Docs 작성이 가능하다고 한다. 이렇게 되면 지금 현재 인수 테스트를 Rest Docs를 위한 테스트로도 사용할 수 있을 것 같다. 그리고 정상적인 시나리오 이외에 예외 사항에 대해서 별도의 문서화 없이 함께 Docs로 관리가 가능하기 때문에 장점이 있다고 생각한다.
따라서 지금 인수테스트를 기반으로 Spring Rest Docs가 가능하다면 지금 바로 도입해도 문제될 부분이 없다고 생각하며, 만약 Rest Docs만을 위한 테스트가 별도로 작성이 필요하고 학습해야하는 부분이 있다면 우선 Swagger를 도입한 이후에 향후에 Rest Docs로 마이그레이션하는 것도 괜찮은 방법이라는 생각이 든다.