React에서 OpenAPI 기반 API 클라이언트 자동 생성하기

React 애플리케이션에서 OpenAPI 스펙을 기반으로 API 클라이언트를 자동 생성하면 개발 생산성을 크게 향상시킬 수 있습니다. 본 글에서는 OpenAPI 스펙을 활용해 React 프로젝트 내에서 자동 생성된 API 클라이언트를 만드는 방법을 소개합니다.

1. OpenAPI란?

OpenAPI는 RESTful API를 구조화하여 표현하는 표준 명세입니다. API 요청, 응답, 인증 방식을 명확하게 정의해주므로 클라이언트와 서버 간 통신을 체계적으로 설계할 수 있습니다.

2. API 클라이언트 자동 생성의 장점

직접 API 요청 함수와 인터페이스를 작성할 필요 없이, OpenAPI 스펙을 읽어 자동으로 타입이 명확한 함수들을 생성합니다. 그 결과 다음과 같은 이점이 있습니다.

• 타입 안정성 보장(TypeScript 지원)
• 코드 중복 감소
• API 변경 시 빠른 대응 가능

3. openapi-generator-cli 설치 및 설정

API 클라이언트를 생성하기 위해 오픈소스 툴인 openapi-generator-cli를 사용합니다. 다음 명령으로 전역 설치 및 사용 가능합니다.

npm install @openapitools/openapi-generator-cli -g

OpenAPI 스펙 json 또는 yaml 파일 준비 후, 아래 명령으로 React용 TypeScript API 클라이언트 생성이 가능합니다.

openapi-generator-cli generate -i ./openapi.yaml -g typescript-fetch -o ./src/api

4. React 프로젝트에 API 클라이언트 통합

생성된 API 모듈에서는 각 엔드포인트에 대한 타입 안전한 함수들이 포함되어 있습니다. React 컴포넌트에서는 다음과 같이 사용할 수 있습니다.

import React, { useEffect, useState } from 'react';
import { DefaultApi } from '../api';

const api = new DefaultApi();

function UsersList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    api.getUsers().then(response => {
      setUsers(response);
    });
  }, []);

  return (
    <div>
      <h2>사용자 목록</h2>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default UsersList;

5. 정리

OpenAPI 기반 API 클라이언트 자동 생성은 복잡한 API 요청 코드를 줄이고, 타입 체킹을 통해 안정적인 개발을 지원합니다. React 프로젝트에 쉽게 통합할 수 있으므로 적극 도입을 권장합니다.