Swagger 적용

도입 이유 & 문제상황

• 초기 프로젝트를 설계 했을 때는 노션을 이용해서 API 명세서를 작성 했었습니다.
• 하지만 매번 API가 수정되고, 만들어 질 때마다 개발에 집중하기 보단 문서를 작성하는 시간 때문에 원활하게 개발을 진행할 수 없었습니다.
• 결론, API 문서화 도구를 적용하기로 하였습니다.

해결방안

• Swagger
• Spring Rest Docs

의견 조율

• Swagger는 객체들에 대한 정보를 제공해 주며, 의존성만 추가해주면 쉽게 설정할 수 있는 장점이 있습니다. 또한 API 테스트 기능 까지 제공하고 있습니다. 하지만 프로덕션 코드에 어노테이션을 추가해 주어야 하기 때문에 가독성이 떨어질 수 있습니다.
• Spring Rest Docs 테스트 기반으로 수행되기 때문에 문서의 신뢰성이 높습니다 또한 프로덕션코드에 영향을 주지 않습니다. 하지만 세부적인 기능을 설정하기 어렵고, API 테스트같은 추가적인 기능을 제공하지 않습니다.

의견 결정

• Swagger를 한번 사용해 본 적있었고, 쉽게 설정하고 다양한 기능을 제공하는 Swagger를 사용하기로 결정하였습니다.
• 프로덕션 코드가 가독성을 떨어질 수 있지만 문서의 가독성이 좋아서 팀원들도 문서를 쉽게 이해할 수 있다는 장점도 의견을 결정하는데 중요한 요소가 되었습니다.