Generación de Swagger/OpenAPI para TypeScript: mejores herramientas

Generación de Swagger/OpenAPI para TypeScript: Guía completa de herramientas

El desarrollo de aplicaciones web modernas en TypeScript está intrínsecamente ligado a la creación de clientes API con seguridad de tipos. Escribir interfaces manualmente para cada endpoint es una tarea tediosa y propensa a errores. Afortunadamente, existe un enfoque potente: la generación automática de código TypeScript a partir de especificaciones OpenAPI (Swagger). En este artículo, analizaremos en detalle las mejores herramientas para esta tarea, sus capacidades y ejemplos de uso.

¿Por qué usar la generación a partir de OpenAPI?

OpenAPI (anteriormente Swagger) es un estándar para describir APIs REST. Al utilizar un archivo de especificación YAML o JSON, obtienes:

• Tipado al 100% — interfaces TypeScript que coinciden exactamente con el esquema de solicitudes y respuestas
• Sincronización con el backend — al cambiar la API, solo necesitas regenerar el código
• Reducción de errores — el compilador de TypeScript detecta discrepancias de tipos en la etapa de desarrollo
• Autocompletado en el IDE — IntelliSense sugiere campos y tipos

Principales herramientas para generar TypeScript desde OpenAPI

1. openapi-typescript-codegen (recomendado)

Esta herramienta ha ganado popularidad gracias a su simplicidad y enfoque moderno. Genera código limpio y bien estructurado con soporte para axios o fetch.

Instalación:

npm install -D openapi-typescript-codegen

Ejemplo de uso:

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

Código generado:

// generated/models/User.tsexport interface User {    id: number;    name: string;    email: string;    role: 'admin' | 'user';}

// generated/services/UserService.tsexport class UserService {    public async getUsers(): Promise<User[]> {        return this.httpRequest.request({            method: 'GET',            url: '/users',        });    }}

Ventajas:

• Soporte para OpenAPI 3.0 y 3.1
• Generación de modelos, servicios y tipos para solicitudes
• Generación opcional de hooks para React Query
• Plantillas personalizables mediante Handlebars

2. OpenAPI Generator (openapi-generator)

Generador oficial de la comunidad OpenAPI. Soporta más de 50 lenguajes, incluyendo TypeScript (varios generadores).

Instalación:

npm install -D @openapitools/openapi-generator-cli

Ejemplo de uso:

npx openapi-generator-cli generate \    -i spec.yaml \    -g typescript-axios \    -o ./generated

Código generado:

// generated/api.tsexport const UsersApiAxiosParamCreator = {    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {        const localVarPath = `/users`;        return {            url: localVarPath,            method: 'GET',        };    }}

Características:

• Generadores: typescript-axios, typescript-fetch, typescript-angular
• Soporte para autorización (OAuth2, API Key)
• Generación de documentación y pruebas
• Funciona mediante CLI o plugins de Maven/Gradle

3. swagger-typescript-api

Generador ligero y rápido, enfocado en TypeScript puro sin dependencias innecesarias.

Instalación:

npm install -D swagger-typescript-api

Ejemplo de uso:

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

Código generado: