Alrededor de OpenAPI en los equipos casi siempre surge al principio la misma confusión: los desarrolladores frontend ven la página con la lista de endpoints únicamente como un manual web para leer con los ojos. Al recibir el enlace a la documentación, el programador abre una pestaña del navegador, despliega las tarjetas de colores de las peticiones, examina los campos de la respuesta y copia a mano interface User o los parámetros de pago en el editor de código. Se confunde el envoltorio visual con la herramienta en sí, aunque la página web es solo un escaparate sobre un archivo de contrato legible por máquinas.
Mientras ese contrato se traslade al proyecto a mano, el frontend sigue siendo rehén del calendario ajeno: si el backend todavía no ha desplegado el entorno de pruebas, la maquetación y la lógica quedan en pausa, y cualquier cambio de nombre de un campo en el servidor solo salta cuando se rompe staging. En el análisis del canal Node.JS ru y el detallado artículo en Хабр, el ingeniero bajo el alias itwillwork desglosó paso a paso cómo convertir un esquema OpenAPI crudo en un pipeline de trabajo para frontend. En esta guía me llamó especialmente la atención cómo la combinación de generador de tipos, servidor mock local y parcheo del esquema desacopla por completo el frontend de la disponibilidad del backend.
El contrato en lugar del manual: cómo extraer el esquema crudo de la documentación web
La especificación OpenAPI (antes Swagger) es un documento en formato YAML o JSON que describe con rigor las rutas de una API REST, los parámetros de llamada y las estructuras de datos. Si comparamos el desarrollo con un restaurante, la interfaz web de la documentación es la carta satinada para los comensales, mientras que el propio archivo OpenAPI es la ficha técnica de cocina con la que se configuran automáticamente la caja, el almacén y la comanda.
Aquí la cadena lógica es directa: si el navegador dibuja una tabla interactiva de métodos en Swagger UI o ReDoc, significa que acaba de descargar por red el archivo fuente con el esquema. No hace falta pedirle por privado al desarrollador backend que te pase el documento: basta con abrir la pestaña Network en las herramientas de desarrollo (DevTools), recargar la página y buscar la petición al archivo .json, .yaml o .yml cuya primera línea indica la versión del estándar (openapi: 3.0.x o 3.1.x).
Veamos cómo cambia esto la práctica. Supongamos que tu equipo toma en el sprint la integración de una nueva pasarela de pagos y del perfil del pagador, pero en el backend solo está listo un borrador temprano ./schema/openapi.yaml y no habrá entorno de pruebas hasta dentro de una semana. Al traerte ese archivo al repositorio, en 5 minutos montas a partir de él tipos estrictos de respuesta y un servidor simulado local, construyendo la interfaz con tranquilidad desde el primer día del sprint.
Tipos limpios sin peso extra en el bundle: cómo funciona openapi-typescript
El primer eslabón de este pipeline es extraer automáticamente interfaces de TypeScript directamente desde el esquema. En un stack moderno (Node.js 18+ y TypeScript 5+) escribir modelos DTO a mano pierde sentido: cuanto más rápido cambia la API al arrancar un producto, mayor es el riesgo de pasar por alto un campo modificado al revisar manualmente.
Durante años los desarrolladores evitaban los mastodontes pesados de generaciones pasadas como @openapitools/openapi-generator-cli, que generan SDKs para más de 50 lenguajes pero arrastran al proyecto clases aparatosas y código de runtime innecesario. En mi opinión, openapi-typescript resuelve la tarea de forma mucho más limpia. Funciona como un compilador puro de esquemas: lee un archivo local o una URL de especificación OpenAPI 3.0/3.1 y traduce las secciones de rutas (paths), operaciones (operations) y modelos (components) a un archivo plano de declaraciones .d.ts sin añadir ni un solo byte al bundle final de JavaScript. Basta con agregar al package.json la llamada npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts, y cualquier cambio de campo en el servidor lo señalará enseguida el compilador tsc antes del commit.
Conexión de tipos con peticiones y servidor mock local en cinco minutos
Para que las declaraciones .d.ts rindan al máximo, las estructuras generadas se enlazan con el cliente de red y se apuntan hacia un servidor mock local mientras el backend real de la pasarela de pagos sigue en desarrollo:
- Para
fetchnativo, como pareja del generador se instala el cliente ligero openapi-fetch de unos 6 KB, que recibe la interfazpathse infiere los tipos de rutas, parámetros y respuestas. - Para TanStack React Query, la herramienta Orval genera hooks de consulta listos para usar, mientras que para Redux Toolkit cumple la misma función @rtk-query/codegen-openapi.
- En la capa BFF sobre Node.js y Express, los tipos compartidos se conectan a los controladores, y express-openapi-validator valida peticiones y respuestas contra el esquema en tiempo de ejecución.
Montemos el circuito funcional para nuestro escenario: instalemos los paquetes de generación y el servidor mock de consola Stoplight Prism, generemos los tipos desde ./schema/openapi.yaml, levantemos el emulador de API en el puerto 4010 y ejecutemos una petición tipada del perfil de usuario:
// En la terminal:
// npm install -D openapi-typescript @stoplight/prism-cli && npm install openapi-fetch
// npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts
// npx prism mock ./schema/openapi.yaml -p 4010
import createClient from 'openapi-fetch';
import type { paths } from './types/api';
const client = createClient<paths>({ baseUrl: 'http://localhost:4010' });
// Autocompletado total de endpoints, parámetros y cuerpo de respuesta:
const { data, error } = await client.GET('/v1/users/{userId}', {
params: { path: { userId: '123' } },
});
Al pasar la interfaz paths a createClient<paths>(), vinculamos de forma estricta la plantilla de dirección '/v1/users/{userId}' con la propiedad obligatoria params.path.userId. Si cometes una errata en la URL o olvidas pasar el identificador, la compilación fallará en la comprobación de tipos, y en los objetos data y error el editor sugerirá de inmediato los campos de éxito y de error.
En el puerto 4010 la petición es atendida por el proceso local prism mock. Lee ./schema/openapi.yaml, valida cabeceras y parámetros de la llamada y devuelve una respuesta JSON basada en los ejemplos del esquema. Conviene tener en cuenta un límite de uso: Prism entrega datos estáticos o aleatorios sin guardar estado entre llamadas. Por eso, para escenarios de varios pasos donde un pago cambia el saldo en la siguiente petición, sobre el esquema se conecta un Service Worker mediante msw-auto-mock o se generan fixtures con las utilidades openapi-sampler y json-schema-faker.
Cuando el contrato miente: parcheo declarativo del esquema con openapi-modifier
En la práctica casi todos los equipos caen en la misma trampa: la especificación del backend rara vez es perfecta. Al escribir YAML a mano, los desarrolladores de servidor cometen erratas: ponen type: int en vez de type: integer, format: datetime en vez de date-time u olvidan type: object en un modelo. Y al autogenerar el esquema desde el código, se cuelan rutas internas /internal/ y /private/ o construcciones que rompen el generador.
El primer impulso es abrir el openapi.yaml descargado o api.d.ts y corregir el fallo a mano rápidamente. Pero ese parche vive exactamente hasta la siguiente actualización del archivo desde el servidor, cuando todas las ediciones manuales quedan sobrescritas (por qué no se deben editar contratos generados a mano lo mostré en detalle en el análisis de autogeneración de tipos desde OpenAPI combinando Laravel y TypeScript). Los linters normales de esquemas tampoco salvan aquí: solo avisan del error en consola, pero no arreglan el archivo ajeno.
Para no esperar correcciones del backend, itwillwork monta antes de la generación de código un pipeline declarativo de transformación mediante la utilidad openapi-modifier. En el archivo openapi-modifier.config.js se define una cadena de reglas (pipeline) que al ejecutar npx openapi-modifier toma ./schema/openapi.yaml y guarda una copia corregida ./schema/openapi.prepared.yaml:
- Corrección puntual de tipos (
patch-component-schema): una regla conpatchMethod: 'merge'localiza un descriptor comoUser.idoPet.idy reemplaza la definición errónea por{ type: 'string', format: 'uuid' }(o corrigeintainteger), conservando el resto de campos del modelo. - Añadir funcionalidades antes de la release del backend (
merge-openapi-specydeepmerge): si para la tareaJIRA-232hay que maquetar una pantalla y el endpoint aún no está en el esquema general, la reglamerge-openapi-specfusiona el borradordocs/feature-JIRA-232.yaml, ypatchMethod: 'deepmerge'agrega una nueva propiedad al modelo. - Limpieza y control de obsolescencia: la regla
filter-endpointscon la expresión regular/^\/internal\//recorta las rutas internas,remove-unused-componentselimina esquemas colgados yremove-deprecatedjunto conremove-parameterquitan parámetros obsoletos para que TypeScript marque solo las llamadas que toca reescribir.
Encadena la preparación del contrato y la generación de tipos en un único script de package.json: primero npx openapi-modifier aplica las reglas comentadas con números de tarea (por ejemplo, JIRA-8752) y genera openapi.prepared.yaml, y acto seguido npx openapi-typescript construye api.d.ts a partir de él. Cuando el backend corrija la errata de su lado, la regla temporal se borra de la configuración con una sola línea.
Al final, la combinación de esquema crudo, servidor mock Prism, parcheo declarativo con openapi-modifier y generador openapi-typescript elimina bloqueos en los sprints: el frontend construye una interfaz funcional de la pasarela de pagos antes de que esté listo el entorno de pruebas. Y si quieres ver ejemplos para RTK Query, React Query y Express o llevarte la guía completa de reglas de transformación, echa un vistazo al artículo original en Хабр.

![Node.JS [ru]](/api/digests/it_development/daily/20261112/assets/sources/we-use-js.jpg?v=96d603ea907a603e2476230869b24b042f87006317785f577b52227c3db5cc47)
