피드로 돌아가기
I stopped manually maintaining OpenAPI specs — here's what I did instead
Dev.toDev.to
Backend

Static Analysis 기반 Single Source of Truth 구현으로 Spec Drift 원천 차단

I stopped manually maintaining OpenAPI specs — here's what I did instead

DocSmithDocSmith2026년 5월 7일3분intermediate

AI 요약

Context

코드와 OpenAPI Spec의 이원화된 관리 체계로 인한 Spec Drift 발생. 수동 업데이트 누락에 따른 API 응답 필드 불일치 및 파트너사 통합 장애 유발.

Technical Solution

  • Manual YAML 관리 방식을 지양하고 코드를 유일한 진실 공급원으로 설정하는 Single Source of Truth 전략 채택
  • Framework-specific Decorator 의존성을 제거하여 특정 프레임워크 락인 문제 해결
  • AST(Abstract Syntax Tree) 파싱을 통한 라우트 정의 및 요청/응답 데이터 구조의 정적 분석 수행
  • 코드 내 타입 정보와 JSDoc을 추출하여 OpenAPI Spec으로 자동 변환하는 DocSmith 아키텍처 설계
  • Express 및 FastAPI 등 다양한 프레임워크에 범용적으로 적용 가능한 스캔 로직 구현

실천 포인트

- API 명세와 구현 코드의 일치 여부를 검증하는 CI 린터 도입 검토 - Decorator 기반 자동 생성 도구(FastAPI, NestJS) 사용 가능 여부 판단 - 프레임워크 제약이 큰 경우 AST 기반 정적 분석 도구를 통한 명세 자동화 방안 탐색 - API 변경 사항이 Spec에 자동 반영되는 Pipeline 구축을 통한 휴먼 에러 제거

태그

#Spec-drift#OpenAPI#Single Source of Truth#AST#Static Analysis
원문 읽기