타입기반 API 문서화 라이브러리 Tspec 소개
The post API 문서화, TS 타입만 있으면 해결! – Tspec appeared first on 리디주식회사 RIDI Corporation.
|| .Module__Anchor { scroll-margin-top: 200px; }
안녕하세요, 만타(Manta) 백엔드 엔지니어 전현성입니다. 이번 파트에서는 TypeScript 타입을 기반으로 API 문서화를 자동화해주는 라이브러리 Tspec의 개발 배경과 사용방법을 소개합니다.
1. 소개
Tspec이란?
API 문서화, 왜 필요할까?
API 문서화의 허점, 관리비용과 신뢰성
기존 솔루션 비교
새로운 솔루션, Tspec
2. Tspec 사용법
1) 프로젝트 설정
2) 스키마 정의
3) API 명세 정의
4) API 문서 생성
5) API 서버 연동 (Express.js)
6) API 테스트
3. 마치며
1. 소개
혹시 TypeScript로 REST API를 만들면서 “타입만으로 API 문서를 자동으로 만들 순 없을까??”라는 생각을 해보신 적 없으신가요?
이러한 기대를 현실로 만들어 주는 라이브러리가 바로 Tspec입니다.
Tspec이란?
TypeScript 타입과 JSDoc을 기반으로 API 문서화를 자동화해주는 라이브러리입니다. 단 몇 줄의 코드 추가만으로 누구나 손쉽게 REST API를 문서화할 수 있도록 도와줍니다.
Demo 영상
Tspec cli를 통해 API 문서화 및 OpenAPI Spec을 생성하는 데모 영상
사용법이 정말 간단하지 않나요?
Tspec의 자세한 사용방법을 본격적으로 소개 드리기에 앞서, API 문서화가 왜 필요하며 기존의 어떤 문제점을 해결하고자 Tspec을 새롭게 개발하게 되었는지 그 개발 배경을 말씀드리고자 합니다.
API 문서화, 왜 필요할까?
REST API를 만들다 보면 다른 개발자에게 API를 어떻게 공유할지, 어떻게 문서화할지 고민해 본 적 있지 않으신가요? 많은 개발자들은 효율적인 API 문서화를 위해 Swagger라고도 불리는 OpenAPI Specification(이하 OpenAPI Spec) 표준 명세를 사용하고 있습니다. OpenAPI Spec을 사용하면 API 문서 생성, 테스트, 버전 관리 등의 이점이 있기 때문입니다.
API 문서화의 허점, 관리비용과 신뢰성
API를 문서화하면 개발자 간 소통 비용이 줄어들고, 개발 생산성이 높아집니다. 누구나 아는 문서화의 장점입니다. 하지만 이를 위해 OpenAPI Spec을 작성하는 일은 매우 지루하고 귀찮은 작업입니다. 그걸 꾹 참고 인내하며 모든 API를 문서화했다고 치더라도 더 큰 문제는 그 이후에 있습니다.
API는 시간이 지나면서 추가, 제거, 수정되기 십상이기에 코드가 변함에 따라 API 문서 또한 최신화해야 합니다. 그렇지 않으면 API 문서는 점차 신뢰성을 잃고 더 이상 사용되지 않는 레거시가 될 수 있습니다.
리디의 OpenAPI Schema 파일들
리디에서도 이러한 문제를 피해 갈 수 없었습니다. 리디는 지난 10년간 서비스를 운영하면서 여러 개발자들을 거쳐 수많은 REST API들이 생겨났습니다. 해당 API들을 문서화하기 위해 리디에서는 OpenAPI Spec을 YAML 파일로 직접 관리하였지만, API의 수정이 생길 때마다 관련 OpenAPI Spec, TypeScript 타입, 그리고 관련 코드를 일일이 수정해야 하는 불편함이 있었습니다. 또한 수정 과정에서 OpenAPI 문법에 익숙하지 않아 스키마를 잘못 수정하거나 변경 사항이 누락될 경우, 문서의 신뢰도를 떨어뜨리기도 하였습니다.
결국 OpenAPI Spec을 직접 관리하는 문서화 방식은 API 수정에 따른 관리 부담이 크며, 수정 과정에서 실수가 발생하기 쉽기 때문에 문서의 신뢰성을 높게 유지하기 어렵다는 것을 알게 되었습니다.
기존 솔루션 비교
그렇다면 TypeScript 타입과 OpenAPI Spec 둘 중 하나를 SSoT(Single Source of Tru