OpenAPI Generator는 OpenAPI 또는 Swagger 사양을 클라이언트 SDK, 서버 스텁, 구성 파일과 같은 실행 가능한 코드로 변환하는 오픈 소스 도구입니다. CLI를 설치하고 사양 파일을 지정한 다음, typescript-axios 또는 spring과 같은 제너레이터를 선택하면 코드를 출력 폴더에 작성합니다. 이 가이드에서는 설치 방법, 사용 가능한 제너레이터 목록 확인 방법, 여러 언어용 클라이언트 및 서버 생성 방법을 보여줍니다.
OpenAPI Generator란 무엇인가요?
OpenAPI Generator는 기계가 읽을 수 있는 API 설명을 읽어 소스 코드를 생성합니다. openapi.yaml(또는 JSON) 파일을 제공하면 해당 API를 호출하는 클라이언트 라이브러리, 이를 구현하는 서버 스텁, 그리고 문서와 구성을 생성할 수 있습니다.
OpenAPI v2(이전 Swagger 형식)와 OpenAPI v3를 모두 지원합니다. 이 프로젝트는 GitHub의 OpenAPITools 조직에서 유지 관리되며, 수십 개의 언어 및 프레임워크용 템플릿을 제공합니다.
핵심적인 차이점은 이것이 코드 제너레이터이지, 문서 제너레이터가 아니라는 점입니다. Swagger UI 또는 Redoc과 같은 문서 도구는 사양을 사람이 읽을 수 있는 HTML 페이지로 렌더링합니다. 반면 OpenAPI Generator는 컴파일하여 배포할 수 있는 코드를 생성합니다. Markdown 문서도 생성할 수 있지만, 주요 기능은 SDK와 스텁입니다.
Swagger Codegen과의 관계
Swagger Codegen을 사용해 본 경험이 있다면, OpenAPI Generator는 익숙하게 느껴질 것입니다. 2018년 5월, Swagger Codegen 버전 2.3.1과 2.4.0 사이에 40명 이상의 주요 기여자 및 템플릿 제작자들이 Swagger Codegen에서 포크(fork)되었습니다.
이 포크는 Swagger Codegen 3.0.0의 방향에 대한 의견 불일치로 발생했습니다. 커뮤니티는 더 빠르고 개방적인 릴리스 주기를 원했습니다. 공식 포크 노트는 이 프로젝트가 Swagger Codegen 2.4.0-SNAPSHOT을 기반으로 한다고 설명하고 있으며, 따라서 두 프로젝트는 깊은 뿌리를 공유합니다. 두 도구를 비교 중이라면, Swagger Codegen 대체 도구 분석에서 실질적인 차이점을 다룹니다.
OpenAPI Generator 설치하기
네 가지 일반적인 설치 경로가 있습니다. 스택에 맞는 것을 선택하세요.
npm (가장 일반적)
npm 래퍼는 대부분의 팀에게 가장 쉬운 진입점입니다. 기본 JAR 파일을 자동으로 다운로드하고 관리합니다.
npm install @openapitools/openapi-generator-cli -g
글로벌 설치 없이 실행할 수도 있습니다.
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
독립형 JAR
OpenAPI Generator는 Java 애플리케이션이므로 Maven Central에서 JAR 파일을 직접 다운로드하여 Java로 실행할 수 있습니다. 이렇게 하면 npm 또는 Homebrew 계층을 완전히 피할 수 있습니다.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
다운로드하기 전에 Maven Central에서 최신 버전 번호를 확인하세요.
Docker
공식 이미지를 사용하면 로컬에 아무것도 설치하지 않고 코드를 생성할 수 있습니다. 작업 디렉토리를 컨테이너에 마운트하여 사양을 읽고 결과를 다시 쓸 수 있도록 합니다.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
사용 가능한 제너레이터 목록 확인하기
무언가를 생성하기 전에 어떤 제너레이터가 있는지 확인하세요. 각 제너레이터는 java, python, spring과 같이 언어와 프레임워크를 대상으로 합니다.
openapi-generator-cli list
간결한 한 줄 보기를 원하면 짧은 플래그를 사용하고 쉼표로 분할합니다.
openapi-generator-cli list -s | tr ',' '\n'
이 목록은 클라이언트 제너레이터(API 호출용)와 서버 제너레이터(API 구현용)를 구분하며, 추가로 문서 및 스키마 제너레이터도 포함합니다.
클라이언트 SDK 생성하기
핵심 명령어는 generate입니다. 이 명령어는 항상 사용할 세 가지 인수를 받습니다.
-i, --input-spec은 사양 파일 또는 URL을 가리킵니다.-g, --generator-name은 실행할 제너레이터를 선택합니다.-o, --output은 출력 디렉토리를 설정합니다.
다음은 Axios를 기반으로 하는 TypeScript 클라이언트입니다.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
이 명령어는 ./client에 타입이 지정된 클라이언트를 작성합니다. 사양의 각 작업은 메서드가 되고, 각 스키마는 모델이 됩니다.
동일한 패턴이 여러 언어에서 작동합니다. 제너레이터 이름과 출력 폴더만 바꾸면 됩니다.
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
코드가 하나의 사양에서 나오기 때문에 모든 클라이언트는 계약과 일관성을 유지합니다. 사양이 변경되면 다시 생성하여 SDK를 업데이트합니다.
서버 스텁 생성하기
서버 제너레이터는 방향을 바꿉니다. API를 호출하는 코드 대신, 라우팅, 요청 모델, 핸들러 인터페이스가 연결된 구현 스캐폴드를 얻게 됩니다. 비즈니스 로직은 직접 채워 넣습니다.
다음은 Spring Boot 서버 스텁입니다.
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
생성된 프로젝트는 사양과 일치하는 컨트롤러와 DTO를 제공합니다. 인터페이스 메서드를 구현하면, 요청 및 응답 형태가 이미 정의되어 있습니다. 이렇게 하면 실행 중인 서버가 게시된 계약과 일치하게 됩니다.
출력 구성하기
기본 출력은 원하는 것과 정확히 일치하는 경우가 거의 없습니다. OpenAPI Generator는 몇 가지 제어 기능을 제공합니다.
추가 속성
대부분의 제너레이터는 --additional-properties(단축 별칭 -p)를 통해 언어별 옵션을 노출합니다. 쉼표로 구분된 key=value 쌍으로 전달합니다.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
각 제너레이터는 자체 속성을 문서화하므로, 허용되는 키의 전체 목록은 제너레이터 페이지를 확인하세요.
구성 파일
명령줄이 길어질 때, 옵션을 구성 파일로 옮길 수 있습니다. JSON과 YAML 모두 지원됩니다.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
구성 파일은 생성 설정을 사양 옆에 있는 버전 관리 시스템에 유지하여 빌드를 재현 가능하게 만듭니다.
파일 무시하기
OpenAPI Generator는 출력 디렉토리에서 .openapi-generator-ignore 파일을 읽습니다. .gitignore와 동일한 구문을 사용합니다. 이를 사용하여 수동으로 편집한 파일을 제너레이터가 덮어쓰는 것을 방지할 수 있습니다.
# .openapi-generator-ignore
*.md
src/custom/**
--ignore-file-override <location>을 사용하여 다른 위치에 있는 무시 파일을 지정할 수 있습니다.
사용자 정의 템플릿
모든 제너레이터는 Mustache 템플릿으로 구동됩니다. 기본 출력이 스타일에 맞지 않으면 템플릿을 복사하고 편집한 다음, -t로 디렉토리를 전달합니다.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
이것은 사용자 정의 헤더, 다른 HTTP 클라이언트 또는 모든 생성된 파일에 적용되는 사내 명명 규칙이 필요할 때 올바른 도구입니다.
CI에서 실행하기
코드 생성은 개발자 한 명의 노트북이 아닌 파이프라인에 속해야 합니다. 사양 변경 시마다 클라이언트를 재생성하여 커밋된 SDK가 계약에서 벗어나지 않도록 합니다. 다음은 npx를 사용하는 GitHub Actions 단계입니다.
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
재생성된 출력이 커밋된 내용과 다르면 빌드를 실패시켜 동기화되지 않은 사양과 SDK를 감지할 수 있습니다.
사양을 단일 진실 공급원으로 유지하기
OpenAPI Generator는 입력된 사양만큼만 좋습니다. 부실한 입력은 부실한 출력을 낳습니다. 모호하거나 유효하지 않은 사양은 모호하거나 깨진 SDK를 생성합니다. 따라서 가장 중요한 단계는 generate를 실행하기 전에 발생합니다. 사양을 정확하고 완전하며 안정적으로 만드는 것입니다.
여기서 Apidog가 중요해집니다. Apidog는 OpenAPI 기반의 올인원 API 플랫폼이므로, 설계 작업과 사양이 동일한 아티팩트입니다. API를 설계하거나 가져오면, Apidog는 OpenAPI 문서를 모든 것의 원천인 단일 진실 공급원으로 유지합니다.
깔끔한 워크플로우는 다음과 같습니다.
- Apidog에서 OpenAPI 사양을 설계하거나 가져옵니다. 브랜치 지원을 통해 Git으로 OpenAPI를 버전 관리하는 것과 유사하게 변경 사항을 격리하여 작업할 수 있습니다.
- 생성하기 전에 사양을 검증하고 린트합니다. OpenAPI 린터와 Swagger 유효성 검사기를 통과한 사양은 더 적은 놀라움과 함께 더 깔끔한 코드를 생성합니다.
- 유효성 검사를 통과한 사양을 내보내고, 이를 OpenAPI Generator에 제공하여 SDK와 스텁을 생성합니다.
또한, 사양을 리포지토리와 동기화하여(예: OpenAPI 사양을 GitHub에 동기화) 배포하기 전에 OpenAPI diff로 변경 사항을 검토할 수 있습니다. 오래된 도구에서 전환 중이라면, API 설계 및 테스트를 위한 Swagger 대체 도구 비교가 좋은 시작점입니다.
Apidog가 멈추고 OpenAPI Generator가 시작되는 지점
여기서 정확하게 짚고 넘어갈 가치가 있습니다. Apidog는 완전한 클라이언트 SDK나 서버 스텁을 생성하지 않습니다. 그것은 OpenAPI Generator의 역할이며, 두 도구는 경쟁 관계가 아닌 상호 보완적입니다.
Apidog는 각 엔드포인트에 대해 다양한 언어 및 HTTP 클라이언트용으로 즉시 복사할 수 있는 클라이언트 요청 스니펫을 제공합니다. 이는 스크립트에 붙여넣을 수 있는 요청별 예제이며, 패키지화된 SDK가 아닙니다. 생성되고 버전 관리되는 라이브러리 또는 서버 스캐폴드의 경우, Apidog가 생성한 사양에 대해 OpenAPI Generator를 실행합니다.
Apidog는 또한 자체 명령줄 테스트 러너인 Apidog CLI를 제공하며, 이는 코드 생성과는 별개입니다. CI에서 API 테스트를 실행하지만, SDK를 생성하지는 않습니다. 다음과 같이 설치하고 사용합니다.
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
--access-token으로 인증 정보를 전달하고, -t는 테스트 시나리오를 선택하며, -e는 실행할 환경을 선택하고, -r은 리포터를 선택합니다. 현재 Node.js LTS 릴리스에서 실행하세요. 설정 세부 정보는 Apidog CLI 설치 가이드와 명령줄에서 REST API 테스트하기 가이드를 참조하세요.
따라서 전체 워크플로우는 Apidog에서 사양을 설계하고 유효성 검사, OpenAPI Generator로 SDK 및 스텁 생성, 그리고 Apidog CLI로 실행 중인 API를 검증하는 것입니다.
Apidog를 신용 카드 없이 무료로 사용해 보세요.
자주 묻는 질문
OpenAPI Generator란 무엇인가요?
OpenAPI Generator는 OpenAPITools 조직의 오픈 소스 도구로, OpenAPI 또는 Swagger 사양에서 코드를 생성합니다. 클라이언트 SDK, 서버 스텁, 문서 및 구성 파일을 생성하며, OpenAPI v2와 v3를 모두 지원합니다.
OpenAPI Generator는 어떻게 사용하나요?
CLI를 설치한 다음(예: npm install @openapitools/openapi-generator-cli -g), 세 가지 플래그(사양용 -i, 제너레이터용 -g, 출력 폴더용 -o)와 함께 generate를 실행합니다. 사용 가능한 모든 제너레이터를 보려면 먼저 openapi-generator-cli list를 실행하세요.
OpenAPI Generator는 어떻게 작동하나요?
사양을 내부 모델로 구문 분석한 다음, 선택한 대상에 대해 Mustache 템플릿을 통해 해당 모델을 렌더링합니다. 각 작업은 메서드 또는 핸들러가 되고, 각 스키마는 타입이 지정된 모델이 됩니다. 출력을 변경하려면 -t로 템플릿을 재정의할 수 있습니다.
OpenAPI 사양에서 클라이언트 SDK를 어떻게 생성하나요?
클라이언트 제너레이터를 선택하고 generate를 실행합니다. 예를 들어, openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client는 타입이 지정된 TypeScript 클라이언트를 빌드합니다. 다른 언어를 대상으로 하려면 typescript-axios를 java, python, go로 바꿉니다.
서버 스텁을 어떻게 생성하나요?
서버 제너레이터를 선택합니다. Spring Boot 스캐폴드의 경우, openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring을 실행합니다. 출력에는 사양의 컨트롤러와 요청 모델이 포함되며, 핸들러 로직은 직접 구현합니다.
OpenAPI Generator와 Swagger Codegen의 차이점은 무엇인가요?
OpenAPI Generator는 더 빠르고 커뮤니티 주도의 릴리스 주기를 원했던 40명 이상의 기여자에 의해 2018년 5월에 Swagger Codegen에서 포크되었습니다. 둘은 공통 기반을 공유하지만, OpenAPI Generator는 이제 자체 로드맵, 제너레이터 세트 및 릴리스 일정을 가지고 있습니다.
OpenAPI 사양에서 PHP SDK를 어떻게 생성하나요?
php 제너레이터를 사용합니다: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. 생성하기 전에 openapi-generator-cli list를 실행하여 정확한 제너레이터 이름과 다른 PHP 프레임워크 옵션을 확인하세요.