openapi-multitarget-codegen

OpenAPI 스펙을 입력으로 받아 아래 3가지 타깃의 코드를 생성하는 npm 배포용 CLI 패키지입니다.

1. TypeScript Kubb
2. Python 타입 코드
3. LangGraph 도구 코드

이 패키지는 특정 프로젝트 구조를 전제하지 않습니다.

• 입력 스펙 경로는 --input으로 받습니다.
• 출력 루트 경로는 --output으로 받습니다.
• 생성 타깃은 --target으로 받습니다.

즉, openapi/openapi.yaml, generated/... 같은 하드코딩된 경로에 묶이지 않고 사용할 수 있게 만드는 것이 목적입니다.

설치

dev dependency

npm install -D openapi-multitarget-codegen

또는:

pnpm add -D openapi-multitarget-codegen

전역 설치

npm install -g openapi-multitarget-codegen

실행 방법

• dev dependency로 설치했다면 다음 형태로 실행하세요.
  • npx openapi-multitarget-codegen ...
  • pnpm exec openapi-multitarget-codegen ...
• 전역 설치한 경우에만 openapi-multitarget-codegen ... 명령을 직접 사용할 수 있습니다.

처음 사용해보기

1. 스펙 최소 구조를 확인합니다.
2. 단일 타깃으로 먼저 생성해 봅니다.
3. 필요한 경우 여러 타깃을 한 번에 생성합니다.
4. Kubb 고급 설정이 필요할 때만 --kubb-config 모드로 넘어갑니다.

npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
npx openapi-multitarget-codegen generate --input ./specs/openapi.yaml --output ./generated --target kubb
npx openapi-multitarget-codegen generate --input ./specs/openapi.yaml --output ./generated --target kubb --target python --target langgraph

문서

• OpenAPI 작성 가이드: docs/openapi-authoring-guide.md
• 예제 스펙: openapi/openapi.example.yaml

GitHub

• Repository: https://github.com/kht2199/openapi-multitarget-codegen
• Issues: https://github.com/kht2199/openapi-multitarget-codegen/issues

지원 타깃

1) kubb

OpenAPI 스펙으로부터 TypeScript 타입 및 fetch client를 생성합니다.

2) python

OpenAPI 스펙으로부터 Python 타입 코드를 생성합니다. 기본 출력 모델 타입은 pydantic_v2.BaseModel입니다.

3) langgraph

OpenAPI operation을 기준으로 LangGraph/LangChain StructuredTool 초안 코드를 생성합니다.

중요:

• LangGraph는 정식 지원 타깃입니다.
• 하지만 구현이 특정 파일 경로나 특정 프로젝트 레이아웃에 하드코딩되어서는 안 됩니다.
• 이 CLI는 LangGraph 타깃도 다른 타깃과 동일하게 인자 기반으로 생성합니다.

CLI 사용법

openapi-multitarget-codegen generate --input <spec> --output <dir> --target <kubb|python|langgraph> [--target ...]
openapi-multitarget-codegen check-spec --input <spec>

공통 옵션

• --input <path> (필수): OpenAPI 파일 경로 (.yaml, .yml, .json)
• --output <dir> (필수, generate 전용): 생성 결과를 쓸 출력 루트 디렉터리
• --target <name> (필수, generate 전용): 생성 타깃 (kubb, python, langgraph)
  • 여러 개를 생성하려면 --target을 반복해서 넘깁니다.
• --clean (generate 전용): 출력 루트를 먼저 비웁니다.

check-spec 범위

• check-spec은 파일 존재 여부와 기본 구조(openapi, paths) 확인에 더해, OpenAPI 문서를 실제로 parse/validate 합니다.
• unresolved $ref, 잘못된 스키마 구조, 문서 수준의 OpenAPI 오류를 조기에 잡는 용도입니다.
• 다만 target별 생성기 호환성까지 전부 보장하는 것은 아닙니다. 즉, kubb, python, langgraph 각각의 세부 제약은 실제 generate 단계에서 추가 확인이 필요할 수 있습니다.

추가 옵션

• --python-model-type <type>
  • 기본값: pydantic_v2.BaseModel
• --kubb-output-dir <path>
  • 기본값: <output>/kubb
  • 상대 경로는 --output 기준으로 해석됩니다.
  • --kubb-config와 함께 사용할 수 없습니다.
• --kubb-format <mode>
  • 기본값: false
  • preset 모드에서만 사용합니다.
  • 허용값: auto, prettier, biome, oxfmt, false
  • 기본값 false는 Kubb 생성은 유지하되 formatter 미설치로 인한 혼란스러운 메시지를 피하기 위한 설정입니다.
  • --kubb-config와 함께 사용할 수 없습니다.
• --python-output-file <path>
  • 기본값: <output>/python/models.py
  • 상대 경로는 --output 기준으로 해석됩니다.
• --langgraph-output-dir <path>
  • 기본값: <output>/langgraph
  • 상대 경로는 --output 기준으로 해석됩니다.
• --langgraph-file <name>
  • 기본값: langgraph_tools.py
• --kubb-client <client>
  • 기본값: fetch
  • --kubb-config와 함께 사용할 수 없습니다.
• --kubb-config <path>
  • Kubb native config 파일을 그대로 사용합니다.
  • 이 모드에서는 해당 config 파일이 Kubb 생성에 관한 입력/출력/플러그인 설정의 source of truth가 됩니다.
  • 다만 이 래퍼 CLI 차원에서는 --input, --output을 계속 요구합니다.
  • --input은 사전 검증에 사용되고, --output은 --clean 처리 기준 디렉터리입니다.
  • 이 패키지는 내장 preset을 만들지 않고 kubb generate --config ...를 pass-through 합니다.
• --kubb-arg <value>
  • 반복 가능 옵션입니다.
  • --kubb-config와 함께만 사용할 수 있습니다.
  • 전달한 값은 kubb generate 뒤에 그대로 추가됩니다.
  • 값이 --watch, --logLevel처럼 --로 시작하면 --kubb-arg=--watch처럼 = 형식으로 전달하세요.

주의: --kubb-output-dir, --python-output-file, --langgraph-output-dir에 주는 상대 경로는 현재 작업 디렉터리가 아니라 --output 디렉터리 기준으로 해석됩니다.

Kubb 사용 정책

이 CLI의 Kubb 지원은 두 가지 모드가 있습니다.

1. 기본 preset 모드
   • 이 패키지에 포함된 기본 Kubb 구성으로 생성합니다.
   • 기본 formatter 설정은 false입니다.
   • formatter를 켜고 싶다면 --kubb-format auto 또는 --kubb-format prettier 같은 식으로 명시합니다.
   • 현재 포함된 핵심 의존성:
     • @kubb/cli
     • @kubb/core
     • @kubb/plugin-oas
     • @kubb/plugin-ts
     • @kubb/plugin-client
2. native config pass-through 모드
   • --kubb-config를 주면 사용자의 기존 Kubb config를 그대로 사용합니다.
   • Kubb의 실제 입력/출력/플러그인/formatter 설정은 config 파일 내용을 따릅니다.
   • 다만 이 래퍼 CLI는 --input, --output을 계속 요구합니다.
   • --input은 OpenAPI 파일 사전 검증에 사용되고, --output은 --clean 기준 루트입니다.
   • 이 모드에서는 --kubb-output-dir, --kubb-client, --kubb-format을 함께 사용할 수 없습니다.
   • 이 경우 추가 Kubb 플러그인은 소비자 프로젝트에서 직접 설치/관리하는 것을 권장합니다.

즉, 이 패키지는 기본 preset에 필요한 핵심 Kubb 플러그인만 포함하고, 나머지 Kubb 생태계는 기존 Kubb CLI/config를 그대로 통과시키는 방향을 따릅니다.

주의: --clean은 항상 --output 루트를 먼저 삭제합니다. --kubb-config 모드에서는 실제 Kubb 출력 위치가 config 내부 설정과 다를 수 있으므로 신중하게 사용하세요.

빠른 OpenAPI 작성 템플릿

아래 템플릿은 이 CLI로 Kubb / Python / LangGraph 생성을 시작할 때 최소한으로 복붙해 쓸 수 있는 예시입니다. 더 자세한 기준은 docs/openapi-authoring-guide.md를 참고하세요.

openapi: 3.0.3
info:
  title: Example API
  version: 0.1.0
servers:
  - url: https://api.example.com
paths:
  /items:
    get:
      operationId: listItems
      summary: List items
      description: Retrieve the current item catalog.
      responses:
        '200':
          description: Successful item list response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
    post:
      operationId: createItem
      summary: Create item
      description: Create a new catalog item from the supplied payload.
      requestBody:
        required: true
        description: Item payload to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateItemRequest'
      responses:
        '200':
          description: Item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
  /items/{itemId}:
    get:
      operationId: getItem
      summary: Get item by id
      description: Retrieve one catalog item using its identifier.
      parameters:
        - in: path
          name: itemId
          required: true
          description: Unique item identifier.
          schema:
            type: string
      responses:
        '200':
          description: Matching item response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      description: Catalog item returned by the API.
      required: [id, name]
      properties:
        id:
          type: string
          description: Stable item identifier.
        name:
          type: string
          description: Display name of the item.
        description:
          type: string
          description: Optional human-readable item details.
    CreateItemRequest:
      type: object
      description: Payload for creating a catalog item.
      required: [name]
      properties:
        name:
          type: string
          description: Name to assign to the new item.
        description:
          type: string
          description: Optional explanatory text for the new item.

체크 포인트:

• 각 operation에 operationId, summary, description을 넣기
• response description을 비워두지 않기
• parameter/property마다 description을 넣기
• request/response schema는 가능하면 components.schemas로 분리하기

예시

Kubb만 생성

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target kubb

예시 출력 위치 (--output ./generated를 준 경우):

• ./generated/kubb/...

기존 Kubb config 그대로 사용

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target kubb \
  --kubb-config ./kubb.config.ts \
  --kubb-arg=--logLevel \
  --kubb-arg=info

이 모드에서는 kubb generate --config ./kubb.config.ts --logLevel info 형태로 pass-through 됩니다. 추가 Kubb 플러그인이 필요하면 해당 플러그인은 소비자 프로젝트에서 직접 설치하면 됩니다. --input, --output은 이 래퍼 CLI의 사전 검증 및 --clean 기준을 위해 계속 필요하지만, Kubb config 내부의 실제 input/output 설정을 덮어쓰지는 않습니다.

Python 타입만 생성

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target python

기본 모델 타입은 pydantic_v2.BaseModel이므로 기본값을 그대로 사용할 때는 --python-model-type을 생략해도 됩니다.

예시 출력 위치 (--output ./generated를 준 경우):

• ./generated/python/models.py

출력 경로까지 세분화해서 생성

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target kubb \
  --target python \
  --target langgraph \
  --kubb-output-dir ./sdk/ts \
  --python-output-file ./sdk/python/api_models.py \
  --langgraph-output-dir ./agent/tools \
  --langgraph-file catalog_tools.py

위 예시는 다음처럼 생성됩니다.

• ./generated/sdk/ts/...
• ./generated/sdk/python/api_models.py
• ./generated/agent/tools/catalog_tools.py

주의: 위 상대 경로들은 현재 작업 디렉터리가 아니라 --output ./generated 기준으로 해석됩니다.

LangGraph 코드만 생성

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target langgraph

예시 출력 위치 (--output ./generated를 준 경우):

• ./generated/langgraph/langgraph_tools.py

여러 타깃 동시 생성

npx openapi-multitarget-codegen generate \
  --input ./specs/openapi.yaml \
  --output ./generated \
  --target kubb \
  --target python \
  --target langgraph \
  --clean

예시 출력 위치 (--output ./generated를 준 경우):

• ./generated/kubb/...
• ./generated/python/models.py
• ./generated/langgraph/langgraph_tools.py

스펙 유효성 확인

npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml

이 명령은 다음을 검사합니다.

• 파일 존재 여부
• 기본 구조(openapi, paths) 존재 여부
• OpenAPI 문서 parse/validate
• unresolved $ref, 잘못된 스키마 구조 등 문서 수준 오류

다만 이 단계가 kubb, python, langgraph 각 타깃 생성기의 세부 호환성까지 모두 보장하는 것은 아닙니다. 타깃별 제약은 실제 generate 단계에서 추가 확인이 필요할 수 있습니다.

현재 출력 정책

출력 루트는 --output으로 받고, 아무 추가 옵션이 없으면 기본값은 아래와 같습니다.

• kubb → <output>/kubb
• python → <output>/python/models.py
• langgraph → <output>/langgraph/<langgraph-file>

필요하면 아래 옵션으로 타깃별 경로를 더 세분화할 수 있습니다.

• --kubb-output-dir
• --python-output-file
• --langgraph-output-dir

상대 경로는 모두 --output 기준으로 해석되고, 절대 경로도 지원합니다.

현재 구현 특징

Kubb

• 임시 Kubb config를 생성해서 실행합니다.
• 입력 스펙 경로와 출력 경로를 동적으로 주입합니다.
• 기본 client는 fetch입니다.

Python

• uvx --from datamodel-code-generator datamodel-codegen ... 기반으로 실행합니다.
• 모델 타입은 --python-model-type으로 바꿀 수 있습니다.

LangGraph

• OpenAPI operation을 순회하면서 StructuredTool 초안 코드를 생성합니다.
• path/query/body를 분리해서 처리하는 기본 골격을 포함합니다.
• 출력 파일명은 --langgraph-file로 조절할 수 있습니다.

왜 이 패키지가 필요한가

실무에서는 같은 OpenAPI 스펙을 기준으로 여러 언어/프레임워크용 코드를 동시에 만들고 싶을 때가 많습니다.

예를 들면:

• 프론트엔드는 TypeScript client가 필요하고
• Python 서버/스크립트는 타입 모델이 필요하고
• 에이전트 계층은 LangGraph 도구 코드가 필요할 수 있습니다.

이 패키지는 그런 상황에서 OpenAPI를 단일 source of truth로 두고, 여러 타깃을 하나의 CLI 인터페이스로 정리하는 데 목적이 있습니다.

예제 검증 스크립트

저장소에는 예제 스펙 기반 검증 스크립트가 들어 있습니다.

npm run check:example-spec
npm run generate:example:kubb
npm run generate:example:python
npm run generate:example:langgraph
npm run generate:example:all

예제 출력은 ./.tmp-output 아래에 생성됩니다.

런타임 요구사항

• Node.js 20+
• npm 또는 pnpm
• Python 3.11+
• uvx 사용 가능 환경 (python 타깃용, 예: brew install uv)

LangGraph 생성 결과를 실제로 실행하려면 별도로 아래 Python 패키지가 필요할 수 있습니다.

• httpx
• pydantic
• langchain-core

아직 남아 있는 확장 포인트

향후 아래 항목은 더 발전시킬 수 있습니다.

• Kubb의 React Query / Zod / MSW 확장 옵션
• Python 출력의 dataclass / TypedDict preset 단순화
• LangGraph naming / auth / filtering 전략 옵션화
• spec lint/report 전용 명령 추가
• dry-run / overwrite 정책 옵션
• npm publish용 release workflow 정리

한 줄 요약

openapi-multitarget-codegen은 OpenAPI 스펙을 입력받아 Kubb, Python 타입, LangGraph 코드를 생성하는 인자 기반 npm CLI 패키지입니다.