OpenAPI → TypeScript 생성기
OpenAPI 3.0/3.1 스펙(YAML/JSON)을 브라우저에서 TypeScript 인터페이스로 변환. $ref, oneOf/allOf, enum, nullable 지원 및 Zod 스키마 동시 출력.
- 브라우저에서 처리
- 도구 입력을 ZeroTool 서버에 업로드하지 않습니다
- 무료 · 회원가입 불필요
WeChat으로 스캔하여 공유
예시·자세한 설명·자주 묻는 질문 실제 출력이 있는 예시, 다른 도구와의 차이, 자주 묻는 질문.
생성되는 내용
- 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요청 본문과 응답 본문만 읽습니다.
관련 도구
- OpenAPI 검증기 (Swagger 유효성 검사) — 타입 생성 전 스펙을 검증.
- JSON → TypeScript — 스펙은 없고 JSON 응답 샘플만 있을 때.
- JSON → Zod 스키마 — 단일 JSON 예시에서 Zod 생성.
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 인터페이스만 필요하다면 끄세요.