API 문서화, TS 타입만 있으면 해결! – Tspec

Context

리디는 10년간 운영하면서 수많은 REST API가 생겼으나, YAML 파일로 직접 관리하는 OpenAPI Spec과 TypeScript 타입을 동기화해야 했다. API 수정 시마다 OpenAPI 문법, 타입, 관련 코드를 일일이 수정해야 했고, 수정 과정에서 스키마 오류나 누락으로 문서 신뢰성이 저하되었다.

Technical Solution

• TypeScript 타입을 SSoT(Single Source of Truth)로 정의: interface 및 type으로 Request/Response 스키마 작성
• JSDoc 주석으로 스키마 문서화: @example 등을 활용해 필드 설명과 예시 추가
• Tspec.DefineApiSpec 타입으로 API 명세 정의: tags, paths, summary, path/query/body 파라미터, responses를 타입으로 명시
• yarn tspec generate 명령으로 자동 생성: TypeScript 타입을 파싱해 openapi.json (OpenAPI Spec) 자동 생성
• Express 미들웨어로 문서 자동 통합: TspecDocsMiddleware를 앱에 등록해 /docs 경로에 Swagger UI 제공
• 핸들러 타입 추론으로 명세 자동 채우기: handler 필드에 컨트롤러 함수 전달 시 path, query, body, responses 자동 추론

Impact

API 문서화에 필요한 관리 비용을 획기적으로 감소시켰다.

Key Takeaway

TypeScript 타입을 API 명세의 단일 진실 공급원으로 사용하면 코드 수정 시 문서가 자동으로 동기화되므로, 기존 프로젝트 구조를 유지하면서 문서 신뢰성을 높게 유지할 수 있다.