API 스키마 한 벌로 OpenAPI 3.1·gRPC Protobuf·TypeScript 클라이언트를 동시에 뽑아내기 — TypeSpec 1.0 실전 가이드

flowchart TD
    A[.tsp 파일 단일 소스] --> B[TypeSpec 컴파일러]
    B --> C[OpenAPI 3.1 에미터]
    B --> D[Protobuf 에미터]
    B --> E[TypeScript 클라이언트 에미터]
    C --> F[openapi.yaml]
    D --> G[service.proto]
    E --> H[TypeScript SDK]
    F --> I[Swagger UI / API 게이트웨이]
    G --> J[gRPC 서버 스텁]
    G --> K[gRPC 클라이언트 스텁]
    H --> L[프론트엔드 / BFF]

import "@typespec/http";
using TypeSpec.Http;
 
// 모델 정의
model Product {
  id: string;
  name: string;
  priceInCents: int32; // 부동소수점 정밀도 문제를 피하기 위해 센트 단위 정수 사용
  category: "electronics" | "clothing" | "food";
}
 
model ProductPage {
  items: Product[];
  total: int32;
  page: int32;
}
 
// 에러 모델 — @statusCode가 없으면 OpenAPI 스펙에서 응답 코드가 `default`로 매핑됨
@error
model NotFound {
  @statusCode statusCode: 404;
  code: "NOT_FOUND";
  message: string;
}
 
// 라우트 정의
@route("/products")
interface Products {
  @get list(@query page?: int32, @query limit?: int32): ProductPage;
  @get read(@path id: string): Product | NotFound;
  @post create(@body product: Omit<Product, "id">): Product;
  @put update(@path id: string, @body product: Product): Product | NotFound;
  @delete remove(@path id: string): void | NotFound;
}

# tspconfig.yaml
emit:
  - "@typespec/openapi3"
  - "@typespec/protobuf"
  - "@typespec/http-client-js"
 
options:
  "@typespec/openapi3":
    output-file: "dist/openapi.yaml"
    openapi-versions:
      - "3.1.0"
  "@typespec/protobuf":
    output-dir: "dist/proto"
  "@typespec/http-client-js":
    output-dir: "dist/client"

# VS Code TypeSpec 확장을 설치하면 문법 강조·자동완성 지원
# marketplace.visualstudio.com 에서 "TypeSpec" 검색
 
# 새 TypeSpec 프로젝트 초기화
npm init -y
npm install -D @typespec/compiler @typespec/http @typespec/openapi3
 
# 빈 프로젝트 뼈대 생성 (tspconfig.yaml, main.tsp 등 자동 생성)
npx tsp init
 
# 컴파일 실행 — dist/ 아래에 아티팩트 생성
npx tsp compile .

// models/order.tsp
import "@typespec/http";
import "@typespec/protobuf";
 
using TypeSpec.Http;
using TypeSpec.Protobuf;
 
@package
namespace OrderService;
 
enum OrderStatus {
  Pending,
  Fulfilled,
  Cancelled,
}
 
model Order {
  @field(1) id: string;
  @field(2) customerId: string;
  @field(3) amountInCents: int32; // 센트 단위 정수, 부동소수점 정밀도 회피
  @field(4) status: OrderStatus;
  @field(5) createdAt: utcDateTime;
}
 
@error
model OrderNotFound {
  @statusCode statusCode: 404;
  code: "ORDER_NOT_FOUND";
  orderId: string;
}
 
// Omit 반복을 피하기 위해 생성 요청 모델을 명시적으로 추출
model CreateOrderRequest {
  customerId: string;
  amountInCents: int32;
}

// services/orders-rest.tsp
import "../models/order.tsp";
using TypeSpec.Http;
using OrderService;
 
@service
@route("/orders")
interface Orders {
  @get list(@query status?: OrderStatus): Order[];
  @get read(@path id: string): Order | OrderNotFound;
  @post create(@body order: CreateOrderRequest): Order;
}

// services/orders-grpc.tsp
import "../models/order.tsp";
using TypeSpec.Protobuf;
using OrderService;
 
@service
interface OrderGrpcService {
  getOrder(req: { id: string }): Order;
  listOrders(req: { status?: OrderStatus }): { orders: Order[] };
  createOrder(req: CreateOrderRequest): Order;
}

# .github/workflows/typespec.yml
name: TypeSpec Compile & Lint
 
on:
  push:
    paths:
      - "api/**/*.tsp"
      - "tspconfig.yaml"
 
jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - name: Install dependencies
        run: npm ci
 
      - name: Compile TypeSpec
        run: npx tsp compile .
 
      # Spectral: OpenAPI 스펙 품질 린팅
      - name: Lint OpenAPI spec
        run: npx spectral lint dist/openapi.yaml
 
      # oasdiff: main 브랜치 대비 브레이킹 체인지 탐지
      - name: Breaking change detection
        run: |
          npx oasdiff breaking \
            https://raw.githubusercontent.com/org/repo/main/dist/openapi.yaml \
            dist/openapi.yaml \
            --fail-on ERR
 
      # 선택: 생성 아티팩트를 저장소에 자동 커밋
      # 대안으로 GitHub Actions 아티팩트 업로드 방식도 유효합니다
      - name: Commit generated artifacts
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: regenerate API artifacts from TypeSpec"
          file_pattern: "dist/**"

// 에미터가 자동 생성한 파일을 임포트
// 실제 경로와 클래스명은 에미터 버전마다 달라질 수 있으니 생성 결과물을 직접 확인하세요
import { OrdersClient } from "../dist/client";
 
const client = new OrdersClient({ endpoint: "https://api.example.com" });
 
// 타입이 완전히 추론됩니다
const orders = await client.orders.list({ status: "Pending" });
orders.forEach((order) => {
  console.log(order.amountInCents); // number 타입으로 추론
});

// packages/common-types/main.tsp
namespace Common;
 
model PaginationParams {
  @query page?: int32 = 1;
  @query limit?: int32 = 20;
}
 
model PagedResponse<T> {
  items: T[];
  total: int32;
  page: int32;
  hasNext: boolean;
}
 
@error
model ApiError {
  @statusCode statusCode: int32;
  code: string;
  message: string;
}

// services/order-service/main.tsp
import "@company/common-types";
using Common;
 
model OrderPage is PagedResponse<Order>;
 
@route("/orders")
interface Orders {
  @get list(...PaginationParams): OrderPage;
}

flowchart TD
    A[API 계약 관리 문제 인식] --> B{현재 팀 상황은?}
    B -->|OpenAPI YAML 수동 관리| C[전환 효과 큼]
    B -->|Code-First 어노테이션 방식| D{gRPC도 지원 필요?}
    B -->|스펙 자동화는 이미 됨| E{gRPC 신규 도입 예정?}
    D -->|예| F[TypeSpec 적극 검토]
    D -->|아니오| G{TypeScript 팀?}
    E -->|예| F
    E -->|아니오| H[현행 유지도 합리적 선택]
    G -->|예| I[경량 도입 고려]
    G -->|아니오| J[OpenAPI Generator 유지도 무방]
    C --> K[파이럿 서비스 하나로 시작]
    F --> K
    I --> K
    K --> L[tsp compile + CI 연동]
    L --> M[팀 전체 롤아웃]