Конвертер схемы OpenAPI в типы TypeScript

Вставьте документ OpenAPI 3.x (или Swagger 2.0) и получите простые объявления interface/type TypeScript для каждой схемы в components.schemas — без сервера, без CLI генерации кода, без npm install.

Ручное копирование схем API в TypeScript утомительно и легко допустить тонкие ошибки: каждый $ref должен быть отслежен до его цели, allOf/oneOf/anyOf нуждаются в правильной форме union/intersection, а пропущенное поле required или nullable молча создает тип, который лжет о том, что на самом деле возвращает API. Этот инструмент решает все это детерминированно из самой спецификации, поэтому результат соответствует документу каждый раз.

Как его использовать

1. Вставьте документ OpenAPI 3.x или Swagger 2.0 — работают как YAML, так и JSON — в поле ввода, или нажмите Попробуйте пример, чтобы загрузить пример спецификации Pet Store.
2. Включите Добавить JSDoc комментарии из описаний схемы, если хотите, чтобы каждый интерфейс, тип и свойство были аннотированы с description своей схемы.
3. Скопируйте или загрузите сгенерированный файл .ts.

Вывод автоматически обновляется при редактировании спецификации.

Что он конвертирует

• Разрешение $ref — каждая ссылка на components/schemas, $defs или (для Swagger 2.0) definitions разрешается по имени, включая ссылки между схемами в разных bucket'ах. В отличие от преобразования в валидатор времени выполнения, простые типы TypeScript не требуют обработки порядка объявления или циклов — интерфейсы и type alias могут ссылаться друг на друга (включая самих себя) в любом порядке, поэтому самореферерирующаяся схема "tree node" просто работает.
• allOf — становится типом пересечения (A & B), один член на запись allOf.
• oneOf / anyOf — становится типом объединения (A | B).
• discriminator — не требует специального синтаксиса: как только каждый член объединения является типом объекта с его собственным свойством литерального типа (kind: "cat" vs kind: "dog"), TypeScript уже сужает объединение по этому свойству. Сгенерированные типы являются дискриминированным объединением в тот момент, когда вы переключаетесь на общее поле.
• nullable: true (OpenAPI 3.0) и type: [T, "null"] (OpenAPI 3.1 / JSON Schema) — оба становятся T | null.
• enum — string enum становится объединением строковых литералов; const становится одиночным типом литерала.
• required / optional properties — обязательные ключи остаются обязательными; все остальное получает ?.
• additionalProperties — false добавляет сигнатуру индекса [key: string]: never;; значение схемы становится & Record<string, T>.
• Неявная форма — схема, которая опускает type, но объявляет properties или items (обычно в написанных вручную спецификациях), по-прежнему читается как объект или массив, а не возвращается к unknown.

Схема объекта выводится как export interface; все остальное (объединение, пересечение, enum, alias массива, только схема $ref) выводится как export type.

Как насчет параметров, тел запросов и путей?

Этот инструмент только читает components.schemas — переиспользуемые формы данных. Он не генерирует типы для paths, параметров операций или оболочек ответов; для этого используйте полный генератор кода против спецификации или вставьте каждую нужную схему отдельно.

Моя спецификация использует Swagger 2.0 (swagger: "2.0") — это работает?

Да, definitions читается так же, как components.schemas. Если вы предпочитаете сначала преобразовать весь документ в OpenAPI 3.x — новые пути $ref, requestBody, servers и все остальное — см. OpenAPI v2 to v3 Converter.

Моя спецификация сначала валидируется?

Нет — этот инструмент предполагает, что документ уже хорошо сформирован и сосредоточен исключительно на генерации типов. Если вы хотите структурную валидацию (отсутствующий operationId, неразрешимый $ref, необъявленный параметр пути) до или вместо преобразования, см. OpenAPI / Swagger Validator.

Мне нужна схема Zod, а не обычный тип TypeScript

См. JSON Schema to Zod Schema Converter — вставьте одну схему (не полный документ OpenAPI), чтобы получить валидирующую схему Zod времени выполнения плюс её выведенный тип TypeScript.

Моя спецификация отправляется куда-то?

Нет. Анализ и генерация типов выполняются полностью в вашем браузере — тот же код, который работает здесь, также питает публичный API и инструмент MCP, и ничто не делает сетевой запрос.