Swagger(Open API) 문서를 기반으로 TypeScript 타입 정의를 자동으로 생성하기

우혁·2024년 7월 29일

타입스크립트를 배우고 프로젝트를 진행하면서 같은 타입이 비슷한 이름으로 중복 선언이 되었던 경험이 있어서 스웨거 문서가 나오면 처음에 모든 타입을 다 정의하고 시작하면 이런 불상사가 줄어들지 않을까라는 생각을 했던 적이 있었는데,

이번 GDC 상사 행사에 참여하면서 멘토님께서 Open API 문서를 YAML 파일로 읽어 타입을 자동으로 정의하여 생산성을 높일 수 있다는 얘기를 듣고 그 방법에 대해 찾아보기 시작했다.

그렇게 해서 찾게 된게 openapi-typescript 라이브러리이다.

타입을 직접 정의하지 않고 자동으로 생성하면 어떤 장점이 있을까?

개발 생산성 향상: 자동으로 타입을 생성함으로써, 개발자는 수동으로 타입을 정의하는 데 드는 시간을 절약할 수 있다.
코드 일관성: 협업을 하다보면 같은 타입을 비슷한 이름으로 중복 선언이 될 수 있는데 그런 불상사를 줄일 수 있다.

interface UserType { // ?!
  id: number;
  name: string;
}

interface UserInfoType { // ?!
  id: number;
  name: string;
}

openapi-typescript

Node.js를 사용하여 OpenAPI 3.0 및 3.1 스키마를 빠르게 TypeScript로 변환해주는 라이브러리이다. (🚨 Open API 2.x는 openapi-typescript 5.x 이전 버전과 호환된다.)

설치

Node.js (20.x 이상 권장)

npm i -D openapi-typescript typescript

설정

{
  "compilerOptions": {
    "module": "ESNext", // or "NodeNext"
    "moduleResolution": "Bundler" // or "NodeNext"
    "noUncheckedIndexedAccess": true // 유형 안전성을 높일 수 있다.
  }
}

사용법

1. 스웨거 문서 YAML 파일 받기

만약 백엔드가 자바로 스웨거 문서를 만들었다면 JSON 형식에서 YAML 형식으로 변환해야 한다.

검색창에 서버주소/v3/api-docs 로 접속해 JSON 형식의 내용들 복사하기

JSON to YAML JSON 형식을 YAML 형식으로 변환해주는 사이트에 가서 변환하기

2. YAML 파일을 프로젝트에 추가하기

나는 types 폴더에 넣어주었다.(types 폴더에 넣지 않아도 된다.)

3. 명령어 입력하기

npx openapi-typescript src/types/openapi.yaml --output src/types/type.d.ts

나는 scr/types/openapi.yaml 파일을 읽어서 src/types경로에 type.d.ts 파일을 생성했는 데 경로랑 파일 이름은 수정해도 무방하다!

4. 타입 사용하기

생성한 타입 파일을 보면 알겠지만 paths, compoents 등등 타입들이 인터페이스로 선언된 것을 볼 수 있다.

import { paths, components } from "@/types/type";

// 타입 가져오기
type GetScheduleDetailResponse = components["schemas"]["ScheduleResponse"];

// 함수 리턴 값에 타입 정의
const getScheduleDetail = async (scheduleId: number): Promise<GetScheduleDetailResponse> => {
  const response = await fetch(`/schedule/${scheduleId}`);
  return response.json();
};