신뢰성 있는 API 명세를 작성하기: Swagger vs Spring REST Docs

[yachimiya]

📋 현재 상황

현재는 API 명세서가 노션으로 관리되고 있으며, 작업 후에 팀원이 노션의 API 명세서를 추가적으로 수정해야 하는 부담이 있습니다.

💡 고려 사항

처음에는 Swagger와 Spring REST Docs를 고려했습니다. Swagger와 Spring REST Docs의 장단점을 비교하면 다음과 같습니다.

🌐 Swagger

Swagger는 마치 API 테스팅 툴인 Postman처럼 직접 요청하듯이 API를 테스트해 볼 수 있는 화면을 제공해서, 동작을 테스트 하는 데 조금 더 특화되어 있습니다.

👍 장점

• Spring REST Docs의 투박한 UI 보다는 상대적으로 이쁜 UI를 가지고 있습니다.
• 문서화와 동시에 직접 테스트도 바로 가능해서 API 동작 테스트에 용이합니다.

👎 단점

• 로직에 애노테이션을 통해서 명세를 작성하게 되는데, 지속적으로 사용하게 되면 명세를 위한 코드들이 많이 붙어서 전체적으로 가독성이 떨어집니다.
• 테스트 기반이 아니기 때문에 문서가 100% 정확하다고 확신할 수가 없습니다.
• 모든 오류에 대한 여러 가지 응답을 문서화할 수 없습니다.

📑 Spring REST Docs

Spring REST Docs를 사용하면 아래와 같은 이점이 있습니다.

👍 장점

• 테스트 기반으로 문서가 작성되어 테스트 코드가 일치하지 않으면 테스트 빌드가 실패하게 됩니다. 따라서 문서를 신뢰할 수 있게 됩니다.
• 테스트 코드에서 명세를 작성하기 때문에 비즈니스 로직의 가독성에 영향을 미치지 않습니다.

👎 단점

• 설정과 초기 설정이 복잡할 수 있고, 문서화에 익숙해지는 데 시간이 걸릴 수 있습니다.
• Swagger와 비교했을 때 실시간으로 API를 테스트하기 어려워 추가적인 도구가 필요할 수 있습니다.

🏁 결론

Swagger와 Spring REST Docs의 장단점을 고려했을 때, 저희의 주된 요구사항은 문서의 신뢰성과 비즈니스 로직의 가독성이라고 생각했습니다. Spring REST Docs는 테스트 기반 문서화로 신뢰성을 제공할 수 있고, 팀원들과의 상의 후 Spring REST Docs가 비즈니스 로직의 가독성을 유지할 수 있다는 점에서 더 적합하다고 판단했습니다. 따라서 저희는 Spring REST Docs를 사용하기로 결정했습니다.