Swagger , Spring REST Docs

Birdie·2023년 7월 16일

API는 소프트웨어 간의 커뮤니케이션을 가능하게 만들고, 이를 위해 명확한 문서화는 필수적입니다.

이번 글에서는 두 가지 인기있는 API 문서화 도구, Spring REST Docs와 Swagger를 비교해보겠습니다.

1. 개요

먼저, 두 도구의 기본적인 특징에 대해 알아봅시다.

이 도구는 테스트 주도 접근법을 사용하여 정확하고 업데이트 된 API 문서를 생성합니다. 이 접근법은 문서가 API와 동기화되어 있음을 보장하며, 테스트 케이스를 통해 사용자가 예상한대로 작동하는지 확인할 수 있습니다.

Swagger는 API 문서화뿐만 아니라 API 디자인, 빌드, 테스트 등의 전체 생애주기를 지원하는 프레임워크입니다. Swagger UI를 통해 쉽게 API를 시각화하고 대화형 문서를 제공할 수 있습니다.

두 도구 모두 쉽게 API 문서를 생성하는데 도움이 되지만, 사용법과 관련된 몇 가지 차이점이 있습니다.

Spring REST Docs는 테스트 기반으로 동작하기 때문에, 적절한 테스트 케이스를 작성하는데 약간의 시간과 노력이 필요합니다. 하지만, 이를 통해 생성된 문서는 실제 API가 어떻게 동작하는지에 대해 매우 정확한 정보를 제공합니다.

Swagger는 직관적인 UI와 코드 주석(annotation)을 통한 문서화로, 개발자에게 API를 빠르고 쉽게 문서화하는 능력을 제공합니다. 그러나 주석이 코드와 동기화되지 않을 경우, 문서의 정확성이 떨어질 수 있습니다.

API는 시간이 지나면서 계속해서 진화하고 변경되기 때문에 문서의 유지 관리는 중요한 부분입니다.

Spring REST Docs는 테스트를 기반으로 하므로, API가 변경될 때마다 테스트를 업데이트해야 합니다. 이를 통해 API 변경 사항이 문서에 즉시 반영됩니다.

Swagger는 주석 기반으로 문서화하므로, API가 변경되면 주석도 수동으로 업데이트해야 합니다. 따라서 이 프로세스는 개발자가 주석을 최신 상태로 유지하는 것에 크게 의존합니다.

Spring REST Docs와 Swagger 모두 강력한 API 문서화 도구입니다. 테스트 주도의 정확성과 가독성을 중시한다면 Spring REST Docs를, 쉬운 사용법과 시각적으로 매력적인 대화형 문서를 원한다면 Swagger를 선택할 수 있습니다.

다음 포스팅에서는 왜 업브렐라 서버 개발팀은 Spring REST Docs를 선택했고, 어떻게 적용하였는지에 대해 알아보겠습니다.