TypeSpec과 OpenAPI 기반의 API 개발 프로세스

TypeSpec을 활용하여 API를 설계하고, 이를 OpenAPI(YAML)로 변환하여 Express 및 Java 프로젝트에 적용가능함

1. TypeSpec의 정의와 역할

TypeSpec은 Microsoft에서 개발한 API 설계를 위한 전용 IDL(Interface Definition Language)임

• TypeScript-like Syntax: TypeScript와 유사한 문법을 사용하여 학습 곡선이 낮고 가독성이 높음
• Design-First Approach: 코드를 먼저 작성하는 것이 아니라, API의 구조와 타입을 먼저 정의하는 설계 우선 방식을 지향함
• Single Source of Truth: 하나의 .tsp 파일에서 다양한 결과물(OpenAPI YAML, JSON Schema, Client SDK 등)을 생성하여 데이터 정합성을 유지함
• High Abstraction: 반복되는 API 패턴이나 공통 모델을 Generic이나 Mixin 기능을 통해 효율적으로 관리함

2. 로컬 컴파일 및 빌드 메커니즘

TypeSpec은 실행 환경이 아닌 빌드 도구로 작동하며, 로컬 개발 환경에서 컴파일 과정을 거침

컴파일 워크플로우

1. 작성: .tsp 확장자 파일에 데이터 모델과 HTTP 엔드포인트 정의
2. 설치: Node.js 환경에서 @typespec/compiler 및 필요한 Emitter 설치
3. 컴파일: 터미널에서 tsp compile . 명령어 실행
4. 출력: tsp-output 디렉토리에 설정된 타겟 파일(예: openapi.yaml) 생성

주요 Emitter 종류