vite-plugin-openapi-ts 대신 openapi-typescript 도입

백엔드 DTO 문서가 불완전한 상황에서 vite-plugin-openapi-ts는 완벽한 schemes.ts 생성을 요구해 빌드 오류를 발생시킵니다. openapi-typescript는 클라이언트 코드 대신 타입 정의만 생성하며, 누락된 스키마를 unknown으로 처리해 컴파일 오류를 방지합니다.

구현 절차 (5분 내 완료)

1. 기존 플러그인 제거

npm uninstall vite-plugin-openapi-ts

2. 새 패키지 설치

npm install -D openapi-typescript

3. 스크립트 추가

{
  "scripts": {
    "generate:types": "openapi-typescript http://localhost:8080/api-docs --output src/core/api-types.ts"
  }
}

4. 타입 생성 실행

npm run generate:types

src/core/api-types.ts에 경로 인터페이스가 생성되며, 스키마 참조 없이 안정적으로 동작합니다.

5. Vue 컴포넌트에서 수동 요청 처리

<script setup lang="ts">
import type { paths } from '@/core/api-types';
import { apiClient } from '@/lib/http';

type PaymentPath = paths['/payment/transactions']['get'];
type QueryParams = PaymentPath['parameters']['query'];
type SuccessResponse = PaymentPath['responses'][200]['content']['application/json'];

async function loadTransactions(filters: QueryParams) {
  const { data } = await apiClient.get<SuccessResponse>('/payment/transactions', { params: filters });
  return data;
}
</script>

6. 타입 헬퍼 확장 (선택)

// src/core/api-utils.ts
import type { paths } from './api-types';

export type ApiRoute = keyof paths;
export type GetResponse<R extends ApiRoute> = 
  paths[R]['get']['responses'][200]['content']['application/json'];
export type PostRequest<R extends ApiRoute> = 
  paths[R]['post']['requestBody']['content']['application/json'];

// 사용 예시
type TransactionFilters = GetResponse<'/payment/transactions'>;
type NewPaymentRequest = PostRequest<'/payment/create'>;

문제 해결 원리

• openapi-typescript는 불완전한 스키마를 unknown 타입으로 추론해 컴파일 중단 방지
• 수동 구현된 HTTP 클라이언트가 자동 생성 코드의 의존성에서 자유로움
• 백엔드 문서 개선 시 타입 정확도 자동 향상

향후 개선 방향

백엔드 문서가 완비되면 다음 선택지 고려:

• 현재 솔루션 유지
• 클라이언트 생성 기능이 포함된 도구 재도입