OpenAPI Generator 도입 이유
프로젝트를 진행하다보면 휴먼에러 또는 커뮤니케이션의 부재 등으로 API 호출에 오류가 발생합니다. 소통이 안되면 문제가 생겨도 어디서 해결해야 하는지 찾는데 시간이 걸리기도 합니다.
Swagger를 활용하면 OpenAPI 문서를 시각화하여 API 명세서를 정의할 수 있어 커뮤니케이션에 많은 도움이 됩니다. 하지만 그럼에도 잦은 코드 변경이 발생하거나 휴먼에러는 생길 수 있죠. 이런 이유들로 인해 OpenAPI Generator를 도입하여 여러가지 편리함과 안전성을 챙기기로 하였습니다. 이번 글에서는 제가 프로젝트에 적용한 방식대로 설명하고 있습니다. 이 외에도 여러가지 사용법과 설정들에 대해서는 아래 깃허브를 참고해주세요.
openapi-generator
OpenAPITools • Updated Mar 28, 2025
OpenAPI 장점
- API 유지보수 효율성 증가 : API 변경이 발생할 때마다 클라이언트 코드를 수정할 필요 없이 자동으로 업데이트 할 수 있습니다.
- 타입 안정성 보장 : TypeScript 기반으로 API 클라이언트를 생성하여 API 요청 및 응답 데이터의 타입을 자동으로 정의할 수 있습니다.
- 중복 코드 제거 및 개발 속도 향상 : API 호출 로직을 직접 작성하지 않고 자동으로 생성할 수 있어 중복 코드를 줄이고 개발 시간을 단축할 수 있습니다. 추가로 일관된 형식을 유지하여 협업 시 소통과 가독성 등 이점이 있습니다.
Swagger문서를 기반으로 생성할 수 있습니다. 먼저 Swagger 문서를 구축하면 클라이언트 코드는 Swagger 스펙에 맞게 자동 작성됩니다.
Swagger 기반 API 스펙 작성
OpenAPI 스펙을 정의하는 API 스펙 파일을 작성해야 합니다. Swagger를 사용한다면 브라우저에서
https://api.example.com/swagger.json 또는 https://api.example.com/swagger.yaml 로 접근하여 파일을 다운로드 합니다. 아래 펫스토어를 예시로 하면
https://petstore3.swagger.io/api/v3/openapi.json 또는 https://petstore3.swagger.io/api/v3/openapi.yaml 입니다.
Swagger CLI를 사용하여 OpenAPI 스펙을 로컬 파일로 저장할 수도 있습니다.
npx swagger-cli bundle https://api.example.com/swagger.json -o ./openapi/api-spec.yaml
OpenAPI Generator 설정 파일 작성
openapi.json 파일을 생성하여 OpenAPI Generator의 설정을 지정합니다. 코드를 생성할 때 참고되는 설정으로 각 프로젝트에 맞게 설정하여 사용할 수 있습니다. { "inputSpec": "./openapi/api-spec.yaml", // OpenAPI 스펙 파일 경로 "outputDir": "./src/apis/generated", // 생성된 코드가 저장될 디렉토리 "generatorName": "typescript-axios", // TypeScript + Axios 기반의 API 클라이언트 생성 "additionalProperties": { "supportsES6": true, // ES6 문법 지원 활성화 "useSingleRequestParameter": true, // API 메서드의 파라미터를 하나의 객체로 묶어서 전달 "withSeparateModelsAndApi": true, // 모델과 API 클래스를 분리하여 생성 "apiPackage": "api", // 생성된 API 클래스가 저장될 패키지명 "modelPackage": "models", // 생성된 모델 클래스가 저장될 패키지명 "enumPropertyNaming": "camelCase", // Enum 속성의 네이밍 규칙을 camelCase로 설정 "withInterfaces": true, // 생성된 모델이 인터페이스로 정의되도록 설정 "usePromise": true, // API 요청을 Promise 기반으로 반환하도록 설정 "disableUserAgent": true // 자동 생성된 API 요청에 User-Agent 헤더 포함 안 함 }, "servers": [ { "url": "{protocol}://{host}", // 서버 기본 URL을 동적으로 설정 "variables": { "protocol": { "enum": ["http", "https"], // 지원하는 프로토콜 목록 "default": "https" // 기본 프로토콜을 HTTPS로 설정 }, "host": { "default": "api.example.com" // 기본 호스트 주소 설정 } } } ] }
OpenAPI Generator CLI를 사용하여 코드 생성
설정 파일이 준비되었으면 OpenAPI Generator CLI를 사용하여 코드를 생성할 수 있습니다.
CLI 명령어 실행 또는
package.json의 스크립트에 추가하여 실행할 수도 있습니다.npx openapi-generator-cli generate -c ./openapi/openapi.json
{ "scripts": { "generate-api": "openapi-generator-cli generate -c ./openapi/openapi.json" } }
스크립트를 추가하였다면 아래 명령어를 통해 사용하시면 됩니다.
npm run generate-api
생성된 파일 구조
코드가 생성되면 다음과 같은 파일 구조를 확인할 수 있습니다. Pet Store API를 통해 생성하였다면 파일명은 다르지만 구조는 동일하게 보일 것 입니다. api와 model을 나누는 등 여러가지 설정들은 openapi.json 파일에 명시한대로 생성됩니다.
📦generated ┣ 📂.openapi-generator ┃ ┣ 📜FILES ┃ ┗ 📜VERSION ┣ 📂api ┃ ┣ 📜auth-api.ts ┃ ┗ 📜users-api.ts ┣ 📂models ┃ ┣ 📜api-auth-login-post401-response.ts ┃ ┣ 📜index.ts ┃ ┣ 📜login-request.ts ┃ ┣ 📜login-response.ts ┃ ┣ 📜user-input.ts ┃ ┣ 📜user-profile.ts ┃ ┗ 📜user.ts ┣ 📜.openapi-generator-ignore ┣ 📜api.ts ┣ 📜base.ts ┣ 📜common.ts ┣ 📜configuration.ts ┗ 📜index.ts
생성된 API 사용하기
이제 생성된 API 클라이언트를 프로젝트에서 사용할 수 있습니다. axios를 사용하거나 rtk query, react query 등 프로젝트에 맞게 API를 커스텀해서 사용할 수 있습니다.
import { AuthApi, Configuration } from "../generated/api"; const config = new Configuration({ basePath: "https://api.example.com" }); const authApi = new AuthApi(config); async function login(username: string, password: string) { try { const response = await authApi.login({ username, password }); console.log("로그인 성공:", response.data.token); } catch (error) { console.error("로그인 실패:", error); } }
