Generación Swagger/OpenAPI para TypeScript: bibliotecas y herramientas

Generación Swagger/OpenAPI para TypeScript: automatización de la creación de clientes API

Al desarrollar aplicaciones web modernas en TypeScript, a menudo surge la necesidad de integrarse con una API REST descrita a través de especificaciones OpenAPI (anteriormente conocidas como Swagger). Escribir manualmente tipos, interfaces y código de cliente no solo consume mucho tiempo, sino que también es propenso a errores, especialmente cuando cambia el backend. Aquí es donde entran en juego las herramientas de generación automática de código TypeScript a partir de especificaciones OpenAPI. En este artículo, analizaremos tres de las soluciones más populares: openapi-typescript, orval y swagger-typescript-api, y compararemos sus capacidades.

¿Por qué es necesaria la generación de TypeScript a partir de OpenAPI?

El objetivo principal es sincronizar los tipos y el código del cliente entre el frontend y el backend. Ventajas de la generación automática:

• Seguridad de tipos: Todos los endpoints, parámetros de solicitud y respuestas obtienen tipos TypeScript estrictos.
• Actualización: Al cambiar la especificación, basta con regenerar el código, sin necesidad de realizar modificaciones manuales.
• Aceleración del desarrollo: El desarrollador obtiene funciones listas para llamar a la API con autocompletado (IntelliSense).
• Minimización de errores: Se eliminan errores tipográficos en nombres de campos y discrepancias de tipos.

openapi-typescript

La biblioteca openapi-typescript (de los creadores de openapi-fetch) es un generador de tipos ligero. Solo crea interfaces y tipos TypeScript, sin generar código de cliente para llamadas a la API. Es la elección ideal para proyectos donde se necesita tipificar estrictamente los datos, pero la forma de llamar a la API queda a criterio del desarrollador (por ejemplo, mediante fetch o axios).

Instalación:

npm install -D openapi-typescript

Ejemplo de uso (generamos tipos a partir del archivo spec.yaml):

npx openapi-typescript ./spec.yaml -o ./types/api.ts

El resultado es un archivo con tipos que se pueden importar:

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

// Tipo para la respuesta de GET /userstype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Ventajas: Minimalismo, generación rápida, excelente soporte para esquemas complejos (allOf, oneOf).
Desventajas: No tiene funciones listas para llamar a la API, se requiere un envoltorio adicional.

orval

Orval es un potente generador que crea no solo tipos, sino también hooks de React completamente funcionales, así como clientes para axios, fetch o Angular. Es especialmente útil en proyectos React donde se utiliza React Query (TanStack Query).

Instalación:

npm install -D orval

Configuración en el archivo orval.config.ts:

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // o 'axios', 'fetch', 'angular'    },  },};

Ejecutar la generación:

npx orval

Ejemplo de un hook generado:

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // data se tipificará automáticamente}

Ventajas: Integración lista con React Query, soporte para mutaciones, gestión automática de caché.
Desventajas: Gran volumen de código generado, dependencia de un cliente HTTP específico.

swagger-typescript-api

La biblioteca swagger-typescript-api ofrece una generación flexible: se pueden obtener tanto tipos simples como un cliente API completo con soporte para varios clientes HTTP (axios, fetch). Una característica distintiva es la posibilidad de personalizar las plantillas de generación.

Instalación: