OpenAPI → TypeScript 생성기

OpenAPI 3.0/3.1 스펙(YAML/JSON)을 브라우저에서 TypeScript 인터페이스로 변환. $ref, oneOf/allOf, enum, nullable 지원 및 Zod 스키마 동시 출력.

  • 브라우저에서 처리
  • 도구 입력을 ZeroTool 서버에 업로드하지 않습니다
  • 무료 · 회원가입 불필요
path 타입 포함을 켜면 오퍼레이션 타입을 감싸는 네임스페이스를 지정합니다. 비워 두면 Components를 사용합니다. 컴포넌트 스키마 이름은 문서에서 가져옵니다.
생성하는 스키마 속성과 해당 Zod 속성을 선택적으로 만듭니다. Path 파라미터는 자체 required 표시를 따릅니다. 변경은 즉시 반영됩니다.
파라미터, JSON 요청 본문과 JSON 응답 타입이 있는 오퍼레이션 네임스페이스를 추가합니다. 루트 네임스페이스로 감쌉니다. 변경은 즉시 반영됩니다.
TypeScript 선언에 Zod 스키마를 추가합니다. 출력에는 Zod import도 포함됩니다. 완전한 OpenAPI 검증기는 아닙니다. 변경은 즉시 반영됩니다.
입력을 Pet Store 스펙으로 바꾸고 현재 네임스페이스와 옵션으로 즉시 생성합니다.
스펙, 출력과 상태를 지우고 네임스페이스와 옵션은 유지합니다. 도구 안의 Ctrl/⌘+L은 네임스페이스도 지웁니다.
OpenAPI 3.0 또는 3.1 문서를 YAML이나 JSON으로 입력하세요. 문서나 네임스페이스를 편집하면 300밀리초 뒤 생성합니다. 파싱 오류는 출력을 지웁니다. 외부 참조는 가져오지 않으며 지원하지 않는 참조는 상태에 표시합니다.
TypeScript 출력
활성화한 path 타입과 Zod 스키마를 포함한 TypeScript 출력 전체를 복사합니다. 출력이 비어 있으면 복사하지 않습니다.

OpenAPI 문서를 입력하거나 예시를 불러와 TypeScript를 생성하세요.

예시·자세한 설명·자주 묻는 질문 실제 출력이 있는 예시, 다른 도구와의 차이, 자주 묻는 질문.

생성되는 내용

  • components/schemas: 각 스키마가 export interface 또는 export type이 됩니다. 객체는 interface, 기본형 / 유니언 / enum / 교차 타입은 type alias로 출력됩니다.
  • $ref: #/components/schemas/... 참조는 타입 이름으로 해석되며, 스펙의 선언 순서를 그대로 따릅니다.
  • oneOf / anyOf: 유니언 타입 A | B | C. allOf는 교차 타입 A & B.
  • enum: 문자열 또는 숫자 리터럴 유니언.
  • nullable: 3.0의 nullable: true와 3.1의 type: ['X', 'null'] 모두 X | null로 변환.
  • format 힌트: format: date-time에는 ISO 8601 JSDoc 주석을 추가하고, format: binary는 Blob이 됩니다.
  • additionalProperties: 인덱스 시그니처 또는 Record<string, T>.

Path 타입(선택)

path 타입 포함을 켜면 각 오퍼레이션마다 타입 엔벨로프가 생성됩니다:

export namespace Components {
export namespace GetPetById {
  export interface PathParameters {
    id: number;
  }
  export type Response200 = Pet;
}
}

오퍼레이션에 operationId가 없으면 method와 path로 합성합니다(예: GetPetsId).

Zod 스키마(선택)

Zod 스키마 포함을 켜면 각 컴포넌트별로 XSchema를 함께 출력합니다:

import { z } from 'zod';

export const PetSchema = z.object({
id: z.number().int(),
name: z.string(),
status: z.enum(["available", "pending", "sold"]),
});

OpenAPI 스펙이 아니라 손으로 쓴 TS 타입에서 Zod를 만들고 싶다면 TypeScript → Zod를 사용하세요.

예시: 내장 Pet Store 명세

예시를 누르면 Pet, NewPet 두 스키마와 세 개의 오퍼레이션이 있는 작은 OpenAPI 3.0.3 명세를 불러옵니다. 출력의 스키마 부분입니다.

export interface Pet {
id: number;
name: string;
tag?: string | null;
status: "available" | "pending" | "sold";
photo?: Blob;
}

export interface NewPet {
name: string;
tag?: string;
}

필수 속성은 필수로 남고 나머지는 ?가 붙습니다. nullable: true는 | null이 되고 format: binary는 Blob이 됩니다. path 타입 포함을 켜면 getPetById가 PathParameters { id: number }와 Response200 = Pet를 가진 Components.GetPetById가 됩니다. Zod 스키마 포함을 켜고 만든 PetSchema는(zod 3.25로 확인) status: "lost"를 거부하고 tag: null을 받아들입니다.

예시: const, 타입 배열, 외부 참조

다음 OpenAPI 3.1 스키마는 const, 타입 배열, 다른 파일에 대한 참조를 씁니다.

openapi: 3.1.0
info: { title: Events, version: 1.0.0 }
paths: {}
components:
schemas:
  Event:
    type: object
    required: [id, kind, createdAt]
    properties:
      id: { type: integer, format: int64 }
      kind: { const: order.created }
      createdAt: { type: string, format: date-time }
      note: { type: [string, 'null'] }
      owner: { $ref: 'https://example.com/schemas/user.yaml#/User' }

도구의 출력입니다.

export interface Event {
id: number;
kind: "order.created";
/** ISO 8601 date-time */ createdAt: string;
note?: string | null;
owner?: unknown /* unresolved $ref: https://example.com/schemas/user.yaml#/User */;
}

type: [string, "null"]은 string | null이 되고, const는 리터럴 타입 "order.created"(Zod에서는 z.literal("order.created"))가 됩니다. user.yaml에 대한 참조는 다른 문서에 있어 도구가 가져오지 않습니다. owner는 unknown이 되고 참조는 주석에 남으며, 상태 표시줄에 "지원하지 않음: https://example.com/schemas/user.yaml#/User에 대한 $ref"가 표시됩니다. 먼저 redocly bundle로 외부 파일을 components에 합친 뒤, 합친 스펙을 붙여 넣으세요.

예시: Zod의 전방 참조와 재귀

Zod 스키마는 JavaScript 상수이므로 정의하는 줄보다 앞에서는 쓸 수 없습니다. 다음 스키마에서 Order는 나중에 선언되는 Customer를 참조하고, Node는 자기 자신을 참조합니다.

components:
schemas:
  Order:
    type: object
    required: [customer]
    properties:
      customer: { $ref: '#/components/schemas/Customer' }
  Customer:
    type: object
    required: [name]
    properties:
      name: { type: string }
  Node:
    type: object
    required: [value]
    properties:
      value: { type: string }
      children:
        type: array
        items: { $ref: '#/components/schemas/Node' }

Zod 출력은 두 참조를 모두 z.lazy로 감싸, 모듈을 불러올 때가 아니라 데이터를 검사할 때 스키마를 찾습니다. 직접 또는 다른 스키마를 거쳐 자기 자신을 참조하는 스키마에는 z.ZodType<Node> 타입 표기도 붙습니다. TypeScript는 자기 초기화 식에 나오는 상수의 타입을 추론하지 못하기 때문입니다(오류 TS7022).

export const OrderSchema = z.object({
customer: z.lazy(() => CustomerSchema),
});
export const CustomerSchema = z.object({
name: z.string(),
});
export const NodeSchema: z.ZodType<Node> = z.object({
value: z.string(),
children: z.array(z.lazy(() => NodeSchema)).optional(),
});

생성된 모듈은 TypeScript 5.9 strict 모드에서 컴파일되고, zod 3.25로 3단계 트리를 검사할 수 있습니다.

제한

  • #/components/schemas/... 참조와 path 타입의 #/components/parameters/...만 해석합니다. 그 밖의 참조(URL, 다른 파일, #/components/responses/...)는 unknown이 되며 상태 표시줄에 목록이 나옵니다.
  • TypeScript 식별자로 쓸 수 없는 스키마 이름은 바뀝니다. 영문자, 숫자, _, $ 외의 문자는 _로(pet-status → pet_status), 숫자로 시작하는 이름은 앞에 _를, unknown이나 class 같은 키워드는 뒤에 _를 붙입니다.
  • 값이 객체나 배열인 const는 unknown이 됩니다. 문자열·숫자·불리언·null은 리터럴 타입이 됩니다.
  • format: int64인 integer는 number가 되어 253을 넘으면 정밀도가 떨어집니다. API가 이런 ID를 문자열로 보낸다면 string으로 바꾸세요.
  • path 타입은 application/json 요청 본문과 응답 본문만 읽습니다.

관련 도구

FAQ

어떤 OpenAPI 버전을 지원하나요?

3.0.x와 3.1.x 모두 지원합니다. OpenAPI 3.1의 `type: ['string', 'null']`은 `string | null`로, OpenAPI 3.0의 `nullable: true`도 동일하게 처리됩니다.

Swagger 2.0은 어떻게 되나요?

Swagger 2.0은 의도적으로 지원하지 않습니다. 먼저 editor.swagger.io(Swagger Editor 내장 변환기)에서 OpenAPI 3.x로 마이그레이션한 뒤 본 도구에 붙여 넣으세요.

원격 $ref도 해석되나요?

아니요. `#/components/schemas/...`(path 타입에서는 `#/components/parameters/...`도)만 해석합니다. URL이나 다른 파일 같은 그 밖의 `$ref`는 주석이 붙은 `unknown`이 되고, 해석하지 못한 참조는 모두 상태 표시줄에 나옵니다. 먼저 `redocly bundle` 등으로 스펙을 한 파일로 합치거나 openapi-typescript CLI를 쓰세요.

내 스펙이 서버로 전송되나요?

전송되지 않습니다. YAML이나 JSON은 이 탭 안에서 파싱해 TypeScript를 만들며, 스펙을 업로드하거나 브라우저 저장소에 저장하지 않고 원격 $ref URL도 가져오지 않습니다. 스펙이나 네임스페이스 편집을 확정하거나 옵션을 바꾸거나 예시를 불러온 뒤 해결되지 않은 참조 없이 타입을 생성하면 도구 이름과 동작 generate만 기록합니다. 입력 중에는 generate를 기록하지 않으며 같은 출력은 중복 집계하지 않습니다. “예시” 버튼은 별도로 example_load를 기록합니다. 스펙과 생성된 타입 내용은 포함하지 않습니다.

Zod 스키마도 함께 받을 수 있나요?

네. **Zod 스키마 포함** 을 켜면 TypeScript 인터페이스와 함께 `z.object({...})` 정의를 출력합니다. 정적 타입과 일치하는 런타임 검증이 필요할 때 유용합니다.

'path 타입 포함'은 무엇을 하나요?

각 오퍼레이션마다 네임스페이스를 만들어 `PathParameters`, `QueryParameters`, `RequestBody`, `Response200` / `Response201` 등을 노출합니다. DTO 인터페이스만 필요하다면 끄세요.