OpenAPI Generator

프론트엔드 개발자가 회사에서 OpenAPI Generator를 처음 보고 놀랐던 이유

회사에 입사한 뒤 가장 인상 깊었던 기술을 꼽으라면 단연 OpenAPI Generator였다. 이전에도 REST API 문서를 읽고 개발한 경험은 있었지만, 이 정도 수준으로 정돈된 문서를 기반으로 타입과 클라이언트 코드까지 자동으로 생성하는 방식은 처음이었다. 특히 프론트엔드 입장에서 API 스펙이 자동화된 형태로 제공된다는 경험은 꽤 충격적이었다.

---

프론트엔드가 백엔드에게 가장 자주 묻는 질문들

프론트엔드 개발을 하다 보면 자연스럽게 API 타입에 대한 질문이 반복된다.

• 응답이 null로 오는 것과 빈 문자열로 오는 건 어떤 차이인가
• 쿼리 파라미터에 빈 문자열을 보내도 되는가
• 어떤 필드가 optional인지, required인지
• 배열이 비어 있는 것인지, null인지
• 특정 필드 타입이 바뀌었는지

이런 질문들은 결국 프론트엔드가 UI 상태 관리와 데이터 처리를 위해 정확한 타입 정보가 필요하기 때문에 발생하는 필연적인 흐름이다. 문제는 이런 정보가 문서나 구글 스프레드시트로 흩어져 있으면 실수가 생기기 쉽다는 점이다.

---

OpenAPI 를 보았을 때 느꼈던 충격

OpenAPI는 이러한 문제를 거의 근본적으로 해결해준다.
OpenAPI Specification(OpenAPI Spec)은 REST API를 표준화된 형식(YAML 또는 JSON)으로 정의하는 문서이다. 이 문서 안에는 다음 정보가 모두 들어 있다.

• 엔드포인트 URL
• HTTP 메서드
• Request 파라미터
• Request Body 구조
• Response Body 구조
• 각 필드의 타입과 required 여부
• 상태 코드 정의

즉, 백엔드가 작성한 명확한 계약서(Contract)가 존재하는 셈이다.
이 계약을 기반으로 문서화도 자동으로 되고 코드 생성까지 가능해진다.

---

OpenAPI Generator: 코드 자동 생성의 핵심

OpenAPI 자체는 스펙 문서다.
여기에 OpenAPI Generator라는 코드를 자동 생성하는 도구를 붙이면 비로소 강력해진다.

OpenAPI Generator는 스펙 문서를 읽고 다음과 같은 코드를 자동으로 생성해준다.

• 프론트엔드를 위한 타입스크립트 타입
• 프론트 API 클라이언트(fetch/axios 기반 함수)
• 모바일(Android, iOS) SDK
• 서버 스켈레톤(Spring, Node 등)
• 모델 클래스

프론트엔드는 여기서 특히 타입스크립트 타입과 API 클라이언트가 큰 도움을 준다.
기존처럼 URL을 직접 적거나 axios 요청 코드를 일일이 작성할 필요가 없다.
이미 생성된 API 함수를 그대로 import하여 사용하면 된다.

예를 들어, 이전에는 이렇게 작성해야 했다.

 

async function getUser(id: string) { return axios.get(`/api/users/${id}`); }

하지만 OpenAPI Generator를 사용하면 다음과 같은 코드가 자동 생성된다.

 

const user = await userApi.getUser({ id });

이 코드에는 이미 다음 정보가 모두 포함되어 있다.

• 올바른 URL
• 올바른 HTTP method
• 백엔드 스펙과 일치하는 타입
• 필요한 파라미터 정의

프론트엔드는 잘못된 타입을 넘기거나 잘못된 파라미터를 호출할 수 없다.
컴파일 타임에 TypeScript가 즉시 에러를 알려주기 때문이다.

---

Maven으로 자동 생성되는 구조

회사에서는 주로 백엔드에서 Maven Plugin을 통해 OpenAPI Generator를 실행하도록 구성되어 있었다. Maven 빌드가 실행될 때마다 자동으로 TypeScript 타입과 API 클라이언트가 생성되어 프론트 레포지토리로 전달되는 구조였다.

이 방식의 장점은 명확하다.

• 백엔드가 스펙을 수정하면
• Maven 빌드 과정에서 자동으로 새로운 타입이 생성되고
• 프론트는 새로운 타입을 받아 빌드 시점에 타입 변경을 감지한다

이러한 구조는 프론트와 백엔드의 타입 안정성을 극적으로 높여준다.
API 변경이 있을 경우 런타임이 아니라 컴파일 단계에서 오류를 발견할 수 있기 때문이다.

---

OpenAPI의 핵심 가치

OpenAPI와 OpenAPI Generator를 함께 사용하면 API 개발 전반의 흐름이 크게 개선된다.

1. API 문서가 자동으로 생성되고 정확성이 유지된다.
2. 프론트는 타입을 직접 만들 필요가 없으므로 실수가 줄어든다.
3. FE/BE 간의 계약(Contract)이 명확해진다.
4. API 변경이 자동으로 반영되어 유지보수가 쉬워진다.
5. 대규모 서비스에서도 일관된 API 구조를 유지할 수 있다.

단순히 문서를 만드는 도구가 아니라, 팀의 협업 방식 전체를 표준화하고 자동화하는 기술에 가깝다고 느꼈다.