openapi-typescript para TypeScript: guía completa con ejemplos

En el desarrollo web moderno, las interfaces API juegan un papel fundamental, y su especificación mediante el estándar OpenAPI (anteriormente Swagger) se ha convertido en el estándar de facto. Sin embargo, mantener manualmente los tipos de TypeScript en sincronía con la especificación OpenAPI es un proceso tedioso y propenso a errores. La librería openapi-typescript resuelve este problema generando automáticamente tipos estrictos de TypeScript basados en tu esquema OpenAPI (v3.0 y v3.1).

El objetivo principal de la librería es garantizar una interacción type-safe con la API. En lugar de declarar interfaces manualmente para cada endpoint, ejecutas un generador que crea un archivo único (o varios) con tipos para todas las solicitudes, respuestas, parámetros y esquemas. Esto no solo ahorra tiempo, sino que asegura que tus tipos estén siempre sincronizados con la versión actual de la API. Si la especificación cambia, solo necesitas regenerar los tipos y el compilador de TypeScript te señalará inmediatamente cualquier inconsistencia en el código.

La librería se utiliza activamente en proyectos donde la fiabilidad y la velocidad de desarrollo son críticas: desde arquitecturas de microservicios hasta aplicaciones SPA. Soporta la generación tanto para el lado del cliente (por ejemplo, para fetch o axios) como para el lado del servidor (por ejemplo, para Express o Fastify). En este artículo, analizaremos en detalle la instalación, los métodos principales, ejemplos reales y errores típicos.

Instalación

Para instalar la librería, usa npm o yarn. El comando instalará tanto el generador como las dependencias necesarias.

npm install openapi-typescript typescript @types/node --save-dev

O mediante yarn:

yarn add -D openapi-typescript typescript @types/node

Si planeas usar los tipos generados en tiempo de ejecución (por ejemplo, para validación), instala adicionalmente openapi-typescript-helpers:

npm install openapi-typescript-helpers

Inicio rápido — ejemplo mínimo funcional

Supongamos que tienes un archivo spec.yaml con una especificación OpenAPI. Vamos a crear un script simple para generar los tipos.

// generate.ts
import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

async function main() {
  const spec = fs.readFileSync('./spec.yaml', 'utf-8');
  const result = await createClient(spec, { format: 'yaml' });
  fs.writeFileSync('./api-types.d.ts', result);
  console.log('Tipos generados en api-types.d.ts');
}

main().catch(console.error);

Ejecuta el script:

npx ts-node generate.ts

Después de esto, en el archivo api-types.d.ts aparecerán todos los tipos correspondientes a tu especificación. Ahora puedes importarlos en tu proyecto:

import type { paths, components } from './api-types';

// Uso del tipo para un endpoint específico
type GetUsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Métodos y funciones principales

1. createClient(schema: string, options?: ClientOptions): Promise<string>

Qué hace: Método principal para generar tipos. Recibe una cadena con la especificación (JSON o YAML) y devuelve una cadena con código TypeScript.

import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

const spec = fs.readFileSync('./spec.json', 'utf-8');
const types = await createClient(spec, { format: 'json' });
fs.writeFileSync('./types.d.ts', types);

2. createClientFromUrl(url: string, options?: ClientOptions): Promise<string>

Qué hace: Carga de forma asíncrona la especificación desde una URL y genera los tipos. Útil para APIs remotas.

                
    

  
También en la biblioteca
  

                
                  
                 Procesamiento de imágenes en C#: cambio de tamaño y recorte (resize, crop)
      
                
                  
                 Rate Limiting en Kotlin: bibliotecas y ejemplos prácticos
      
                
                  
                 Hugging Face Transformers: guía práctica de modelos NLP en Python
      
                
                  
                 Colas de tareas en Swift: GCD, OperationQueue y Swift Concurrency
      
                
                  
                 Prophet: pronóstico de series temporales de Facebook en Python