tsoa 란? annotation을 통해 swagger 로 api 문서 자동화를 해주는 프레임워크

왜 tsoa?

• 현재 api 명세(문서화)를 postman 을 통해 관리하고 있음
• 요구사항 변경시, 코드의 변경사항을 postman 에 즉각적으로 반영하지 못하고 있음

• 코드상으로 api 문서 자동화를 가능하게 할 수 있지 않을까? 라는 생각으로 하게 됨

• 공식 문서
  • https://tsoa-community.github.io/docs/getting-started.html

  

사용 예시

• annotaion 을 통해 라우터 기능 대체
  • @Route(”users”) ⇒ router.[http메소드](”users”)
  • @Get() ⇒ router.get(”users”)
    • @Get(”{userId}”) ⇒ router.get(”users/:userId”)
  • @SuccessResponse() : 성공인 경우 응답 결과 (실패 처리도 물론 가능)
• swagger 로 자동 변환해줌

장점

• 라우터 작성 필요 x
• 코드 수정시 변경사항 어노테이션(tsoa) 반영하면 별도 문서화 작업 필요 x
  • swagger 로 자동 문서화됨

단점 (우려되는 점)

• custom middleware를 추가하기 어려움
  • ex)AuthRoutes.patch(“/api/v2/users/password”,verifyTokenFromSession,sanitizer(auth.credentialValidator),user.controller.updatePassword);
  • 관련 이슈 https://github.com/lukeautry/tsoa/issues/948
• api 문서화, 테스트 도구를 postman에서 swagger 로 변경해야함
• 프레임워크에 의존적이게 됨(명백한 단점은 아님!)
  • tsoa 가 현재 생태계에서 활발하게 사용되진 않는 것 같음
• 러닝커브

저의 의견은요..! 🙋‍♀️

• tsoa 를 적용하는데는 문제가 없어보입니다. 다만 middleware를 controller 단으로 이동시켜야 할 것 같습니다.
• api 테스트 도구가 변경되는 점과 새로운 프레임워크를 적용한다는 점에서 생각보다 많은 리소스가 들어갈 것이라고 예측됩니다.
• tsoa 가 생태계에서 매우 활발하게 사용되진 않는데, 해당 프레임워크를 메인 프로덕트에 반영해도 될지 걱정이 되긴 합니다.
• 필자는 swagger 에도 익숙하지 않기 때문에 controller의 메소드별로, 문서화를 위한 annotaion이 있는 형태가 아직까진 가독성이 매우 좋아보이진 않습니다. (이건 저의 문제일수도😭)
• 때문에 저의 개인적인 생각으로는 기존 형태(라우터 수기 작성)를 유지하고, api 명세 변경시 작업자가 postman에 더 책임감있게 반영하여 유지하는 것이 좋아보이긴합니다.