¿Cuáles son las mejores herramientas para generar tipos de TypeScript a partir de una especificación OpenAPI? #

TypeScript se ha convertido en el lenguaje dominante para el desarrollo de JavaScript en el frontend y full-stack, y una de sus características más potentes es su sistema de tipos estático. Al trabajar con API REST descritas mediante especificaciones OpenAPI, generar los tipos de TypeScript directamente a partir de la especificación elimina toda una clase de errores en tiempo de ejecución causados por discrepancias de tipos entre la API y sus consumidores. En lugar de mantener manualmente definiciones de tipos que pueden desviarse de la API real, los equipos pueden generarlas de forma automática y mantenerlas sincronizadas a medida que la API evoluciona. Este artículo repasa las mejores herramientas disponibles para generar tipos de TypeScript a partir de especificaciones OpenAPI.

¿Por qué generar tipos de TypeScript a partir de OpenAPI? #

Escribir a mano las interfaces de TypeScript para los cuerpos de solicitud y respuesta de la API es tedioso y propenso a errores. Cuando la API cambia, los tipos mantenidos manualmente pueden no actualizarse al mismo tiempo, lo que provoca errores silenciosos en tiempo de ejecución que el sistema de tipos de TypeScript habría detectado. Generar los tipos a partir de la especificación OpenAPI garantiza lo siguiente:

• Precisión: los tipos reflejan exactamente el esquema de la API tal como se describe en la especificación.
• Coherencia: todos los consumidores de la API usan las mismas definiciones de tipos.
• Productividad: los desarrolladores obtienen autocompletado y comprobación de tipos en el IDE para las cargas útiles de la API sin configuración adicional.
• Detección de cambios: al regenerar los tipos tras una actualización de la API, los errores de compilación de TypeScript salen a la luz de inmediato en los puntos de llamada afectados por el cambio.

1. openapi-typescript #

openapi-typescript es el generador de tipos de TypeScript dedicado más popular para OpenAPI. Genera tipos de TypeScript puros (sin código de ejecución) a partir de documentos OpenAPI 2.0, 3.0 y 3.1. Su principal ventaja es que produce definiciones de tipos ligeras y legibles que no requieren ninguna dependencia en tiempo de ejecución.

Instalación y uso #

npm install -D openapi-typescript typescript
npx openapi-typescript openapi.yaml -o src/types/api.d.ts

También admite URL remotas:

npx openapi-typescript https://api.example.com/openapi.yaml -o src/types/api.d.ts

Resultado generado #

Para un esquema como este:

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string

openapi-typescript genera lo siguiente:

export interface components {
  schemas: {
    User: {
      id: string;
      email: string;
      name?: string;
    };
  };
}

openapi-fetch: cliente fetch con seguridad de tipos #

openapi-typescript se combina con openapi-fetch, un pequeño envoltorio de fetch que usa los tipos generados para garantizar la seguridad de tipos en cada llamada a la API:

import createClient from "openapi-fetch";
import type { paths } from "./types/api.d.ts";

const client = createClient<paths>({ baseUrl: "https://api.example.com" });

const { data, error } = await client.GET("/users/{id}", {
  params: { path: { id: "123" } },
});
// data is typed as the 200 response body
// error is typed as the error response body

Este enfoque resulta especialmente atractivo para los equipos que prefieren un envoltorio de fetch delgado y sin dependencias en lugar de un generador de SDK completo.

2. openapi-generator (clientes de TypeScript) #

openapi-generator es el generador de código más completo del ecosistema OpenAPI y admite más de 50 generadores de clientes, entre ellos varios destinos de TypeScript:

• typescript-fetch: genera un cliente basado en fetch.
• typescript-axios: genera un cliente basado en Axios.
• typescript-angular: genera un servicio de Angular que usa HttpClient.
• typescript-node: genera un cliente para Node.js.

Uso #

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o src/api-client

El código generado incluye interfaces de modelos, métodos de clases de API y serialización de solicitudes y respuestas. Admite una configuración avanzada mediante las opciones --additional-properties para controlar las convenciones de nomenclatura, el estilo de las enumeraciones y más.

openapi-generator es la mejor opción cuando los equipos necesitan un cliente de API completo y con todo incluido, y no solo definiciones de tipos.

3. Hey API (antes openapi-ts) #

Hey API (el paquete @hey-api/openapi-ts) es un generador de clientes OpenAPI moderno, centrado en la ergonomía y la capacidad de configuración de TypeScript. Admite OpenAPI 2.0, 3.0 y 3.1 y puede generar:

• Tipos de TypeScript para esquemas, parámetros y respuestas.
• Código de cliente HTTP para fetch, Axios o transportes personalizados.
• Hooks de integración con TanStack Query (React Query).
• Código de validación de esquemas con Zod.

npm install -D @hey-api/openapi-ts
npx openapi-ts --input openapi.yaml --output src/client --client fetch

La arquitectura de plugins de Hey API permite a los equipos componer exactamente el resultado que necesitan, lo que la hace muy flexible para las aplicaciones modernas de React y Next.js.

4. Orval #

Orval es un generador de clientes de TypeScript creado específicamente para los ecosistemas de React y Vue. Genera clientes de API tipados junto con hooks de integración para bibliotecas populares de obtención de datos:

• TanStack Query (React Query / Vue Query)
• SWR
• Servicios de Angular
• Svelte Query

npm install -D orval
npx orval --input openapi.yaml --output src/api

Orval es ideal para los equipos que crean frontends con React o Vue y quieren no solo tipos, sino también hooks de obtención de datos listos para usar que se correspondan con las operaciones de la API. La configuración se realiza mediante un archivo orval.config.ts, con un control detallado de la estructura de salida, la nomenclatura y la generación de mocks.

5. Zodios #

Zodios adopta un enfoque singular: en lugar de generar interfaces de TypeScript, genera esquemas de Zod, es decir, validadores en tiempo de ejecución que también sirven como fuente de los tipos de TypeScript. Esto ofrece, en un solo paso, seguridad de tipos en tiempo de compilación y validación de las respuestas de la API en tiempo de ejecución.

El paquete complementario openapi-zod-client genera clientes compatibles con Zodios a partir de documentos OpenAPI:

npx openapi-zod-client openapi.yaml -o src/api-client.ts

El cliente generado valida las respuestas en tiempo de ejecución y detecta incumplimientos del contrato de la API que TypeScript por sí solo no puede detectar.

6. Kiota (Microsoft) #

Kiota es el generador de clientes de API de código abierto de Microsoft, diseñado para el SDK de Microsoft Graph pero generalizado para cualquier API OpenAPI 3.x. Admite TypeScript además de C#, Java, Go, Python, PHP y Ruby.

Kiota genera un cliente fluido y orientado a recursos, con un estilo de API distintivo:

const client = createApiClient(requestAdapter);
const user = await client.users.byUserId("123").get();

Hace hincapié en reducir al mínimo el código generado mediante una biblioteca central compartida (@microsoft/kiota-abstractions) en lugar de generar código repetitivo para cada SDK. Kiota es especialmente adecuado para entornos empresariales que ya utilizan herramientas de Microsoft.

Cómo elegir la herramienta adecuada #

Integración en un pipeline de compilación #

La generación de tipos debe formar parte del proceso de compilación automatizado para que los tipos estén siempre sincronizados con la última especificación de la API:

// package.json
{
  "scripts": {
    "generate:api": "openapi-typescript openapi.yaml -o src/types/api.d.ts",
    "prebuild": "npm run generate:api"
  }
}

En CI, los tipos generados pueden incluirse en el repositorio, y cualquier diferencia entre los tipos confirmados y los recién generados sirve para detectar cambios en la API que no se reflejaron en las definiciones de tipos.

Conclusión #

Generar tipos de TypeScript a partir de especificaciones OpenAPI es una de las prácticas de mayor impacto para los equipos de frontend y full-stack que consumen API REST. Herramientas como openapi-typescript, Hey API y Orval facilitan mantener tipos precisos y actualizados con un esfuerzo mínimo. Al integrar la generación de tipos en el pipeline de compilación, los equipos eliminan toda una categoría de errores de integración con la API y mejoran notablemente la experiencia de desarrollo de quienes la consumen.

Última actualización: 29 de abril de 2026.