Conversor de Esquema OpenAPI para Tipos TypeScript

Cole um documento OpenAPI 3.x (ou Swagger 2.0) e obtenha declarações simples de interface/type TypeScript para cada esquema em components.schemas — sem servidor, sem CLI de geração de código, sem npm install.

Copiar esquemas de API manualmente para TypeScript é tedioso e fácil cometer erros sutis: cada $ref deve ser rastreado até seu destino, allOf/oneOf/anyOf precisam da forma union/intersection correta, e um field required ou nullable perdido produz silenciosamente um tipo que mente sobre o que a API realmente retorna. Esta ferramenta resolve tudo isso deterministicamente a partir da própria especificação, para que o resultado corresponda ao documento todas as vezes.

Como usá-lo

1. Cole seu documento OpenAPI 3.x ou Swagger 2.0 — YAML ou JSON funcionam — na caixa de entrada, ou clique em Experimente um exemplo para carregar uma especificação de exemplo da Pet Store.
2. Ative Adicionar comentários JSDoc das descrições do esquema se desejar que cada interface, type e propriedade seja anotada com a description do seu esquema.
3. Copie ou baixe o arquivo .ts gerado.

A saída é atualizada automaticamente à medida que você edita a especificação.

O que ele converte

• Resolução de $ref — cada referência a components/schemas, $defs, ou (para Swagger 2.0) definitions é resolvida pelo nome, incluindo referências entre esquemas em diferentes buckets. Ao contrário de converter para um validador de runtime, tipos TypeScript simples não precisam de tratamento de ordem de declaração ou ciclo — interfaces e type aliases podem referenciar um ao outro (incluindo a si mesmos) em qualquer ordem, então um esquema de "tree node" autorreferenciado simplesmente funciona.
• allOf — torna-se um tipo de interseção (A & B), um membro por entrada allOf.
• oneOf / anyOf — torna-se um tipo de união (A | B).
• discriminator — não precisa de sintaxe especial: uma vez que cada membro da união é um tipo de objeto com sua própria propriedade literal-typed (kind: "cat" vs kind: "dog"), TypeScript já limita a união nessa propriedade. Os tipos gerados são uma união discriminada no momento em que você alterna no campo compartilhado.
• nullable: true (OpenAPI 3.0) e type: [T, "null"] (OpenAPI 3.1 / JSON Schema) — ambos tornam-se T | null.
• enum — um enum de string torna-se uma união de literais de string; const torna-se um tipo de literal único.
• required / optional properties — chaves obrigatórias permanecem obrigatórias; todo o resto recebe um ?.
• additionalProperties — false adiciona uma assinatura de índice [key: string]: never;; um valor de esquema torna-se & Record<string, T>.
• Forma implícita — um esquema que omite type mas declara properties ou items (comum em especificações escritas à mão) ainda é lido como um objeto ou array em vez de recorrer a unknown.

Um esquema de objeto é emitido como export interface; tudo o mais (uma união, uma interseção, um enum, um alias de array, um esquema de $ref-only) é emitido como export type.

E quanto aos parâmetros, corpos de solicitação e caminhos?

Esta ferramenta apenas lê components.schemas — as formas de dados reutilizáveis. Não gera tipos para paths, parâmetros de operação ou envelopes de resposta; para isso, use um gerador de código completo contra a especificação, ou cole cada esquema que você precisa individualmente.

Minha especificação usa Swagger 2.0 (swagger: "2.0") — isso funciona?

Sim, definitions é lido da mesma forma que components.schemas. Se preferir que o documento inteiro seja convertido primeiro para OpenAPI 3.x — novos caminhos $ref, requestBody, servers e tudo mais — veja OpenAPI v2 to v3 Converter.

Minha especificação é validada primeiro?

Não — esta ferramenta pressupõe que o documento já está bem formado e se concentra puramente na geração de tipos. Se deseja validação estrutural (missing operationId, um $ref não resolvível, um parâmetro de path não declarado) antes ou em vez de converter, veja OpenAPI / Swagger Validator.

Preciso de um esquema Zod, não de um tipo TypeScript simples

Veja JSON Schema to Zod Schema Converter — cole um esquema (não um documento OpenAPI completo) para obter um esquema Zod validador de runtime mais seu tipo TypeScript inferido.

Minha especificação é enviada para algum lugar?

Não. A análise e a geração de tipos executam inteiramente no seu navegador — o mesmo código executado aqui também alimenta a API pública e a ferramenta MCP, e nada faz uma solicitação de rede.