백엔드
RESTful API validation 자동화 하기
두줄요약
TypeScript 인터페이스 주석에서 JSONSchema를 생성해 ajv 검증과 API 문서화를 자동화했습니다. Fastify, Swagger, TypeDoc 연동의 장점과 버전·표현력 제약을 함께 설명합니다.
문제 상황
- 엄격한 RESTful API 입력값 검증에 따른 개발 비용 증가와 느슨한 검증에 따른 장애 위험
- 검증 스키마, Swagger 문서, TypeDoc 문서의 개별 관리로 인한 최신화 부담
구조와 흐름
- TypeScript Request 인터페이스의 JSDoc 주석과 제약 조건을 JSONSchema로 변환
- 생성된 JSONSchema를 ajv 및 fastify.js 라우트에 등록해 요청 검증 수행
- fastify-swagger와 TypeDoc으로 API·인터페이스 문서 자동 생성
선택 이유
- 단일 인터페이스 정의를 검증과 문서화의 공통 원천으로 활용
- JSONSchema 등록만으로 Swagger.io 문서 최신 상태 유지
- Jenkins 배포 과정에서 생성 문서를 S3에 업로드하는 운영 방식
주의할 점
- JSONSchema, ajv, fastify.js 간 연동과 definition 관리에 필요한 학습 비용
- JSONSchema·ajv 버전 변화와 fastify.js 호환성 제약
- ts-json-schema-generator의 mapped access 변환 오류 및 JSONSchema의 커스텀 검증 한계
