De cientos de OpenAPI a una “fábrica” de cumplimiento: automatizar sin romper contratos
Migrar un inventario masivo de APIs hacia API Management no es solo infraestructura: es gobernanza, seguridad y contratos. Así usamos OpenRewrite para estandarizar especificaciones sin tocar lo que los consumidores ya usan.
Basado en la presentación Automated API Migration Strategy (caso de uso interno, track de modernización hacia Azure API Management).
En muchas organizaciones financieras y reguladas, el reto no es “subir” una API al gateway: es hacerlo sin romper rutas, parámetros ni operationId, al tiempo que se cumple un checklist de arquitectura y seguridad. Cuando el inventario habla de órdenes de magnitud (en nuestro caso, alrededor de 400 definiciones en un mismo track de migración), el margen de error manual se vuelve inaceptable.
La respuesta no fue más horas-hombre repartiendo YAML a mano, sino automatización declarativa centrada en OpenRewrite.
El problema en una frase
Migrar a escala requiere precisión milimétrica repetida cientos de veces. La prueba de concepto tomó cinco APIs representativas de dominios distintos y fijó una regla de oro: cambios no disruptivos; el contrato observable por clientes y SDKs debe permanecer estable.
Bifurcar contrato y ejecución
La estrategia separa dos mundos que a menudo se mezclan y generan deuda:
Especificación OpenAPI (YAML) — metadatos, forma del contrato, alineación a lineamientos de gobierno (por ejemplo criterios tipo DIS02/DIS03 en nuestro marco).
Políticas en API Management — comportamiento en runtime (HSTS, CORS, cabeceras de caché) como plantillas reutilizables, fuera del YAML cuando no corresponde mezclar preocupaciones.
Para el primer frente, el motor fue OpenRewrite con rewrite-yaml: transformaciones sobre el documento sin rediseñar la API. Para el segundo, artefactos versionados (por ejemplo en un directorio tipo apim-policies/) que el despliegue aplica de forma homogénea en el perímetro.
Qué aporta OpenRewrite (y por qué no es un buscar/reemplazar)
OpenRewrite actúa como motor de transformación semántica: opera sobre la estructura del YAML (en la práctica, un árbol sintáctico), no sobre texto plano. Eso permite reglas que respetan intencionalidad y contexto.
El flujo es deliberadamente simple de explicar y de auditar:
Entrada: YAML legado.
Proceso: motor de recetas (pom.xml / rewrite.yml con recetas declaradas).
Salida: YAML estandarizado.
Tres beneficios que en el terreno regulado pesan mucho:
Declarativo — las reglas viven en configuración versionable.
Seguro para el negocio — se preservan rutas, métodos HTTP y cuerpos de request/response acordados.
Auditable — se pueden exportar tablas de datos y evidencia de hallazgos y cambios.
Ejemplo de idea (no de cliente): recetas como MergeYaml para completar nodos faltantes (info.contact, externalDocs) sin pisar lo que ya definió el equipo, con parámetros del estilo acceptTheirs: true donde aplica.
De lineamientos a acciones automáticas
En la POC se mapearon ocho criterios críticos a acciones concretas:
En el spec (OpenRewrite): inyección o normalización de contacto y documentación externa, versión en SemVer, forzado de HTTPS en servers, verificación de esquemas de seguridad sin cambiar el mecanismo de autenticación elegido por la API.
En runtime / APIM: plantillas para HSTS, CORS alineado a frontends y MFE, y Cache-Control (por ejemplo no-store donde hay datos sensibles).
Así se cumple gobierno sin confundir “seguridad en el borde” con “metadatos del contrato”.
Transformación solo en especificación (non-breaking)
Las recetas de migración OpenAPI aplicaron, entre otras cosas:
Sustitución inmediata de http:// por https:// en URLs de servidor.
Inyección de bloques info.contact y externalDocs con políticas de fusión que no machacan claves existentes.
Normalización de versiones informales (p. ej. v1) hacia SemVer esperado por el portal de desarrolladores.
El antes y el después en el deck muestra exactamente ese patrón: el contrato gana madurez documental sin reescribir operaciones.
Dry-run: el simulador de vuelo
Antes de tocar repositorios “de verdad”, el flujo apuesta por dryRun: procesar lotes de archivos en memoria, generar un rewrite.patch cuando hay diferencias y no aplicar cambios hasta validar.
En integración Maven, opciones como exportar datatables y no fallar ciegamente en dry-run permiten que el equipo vea el impacto propuesto. Si la salida indica que no hay cambios, es una señal fuerte de que el spec ya cumple las recetas: menos sorpresas en CI.
Auditoría solo lectura: detectar antes de migrar
Paralelamente, una receta de auditoría (FindKey / FindProperty sobre rutas de YAML) marca incumplimientos sin modificar archivos: versión OpenAPI, contacto, documentación externa, URLs de servidor, esquemas de seguridad donde aplique.
El valor es doble: visibilidad masiva del inventario y alertas tempranas (por ejemplo datos sensibles en path o query) con escalamiento a seguridad antes del cutover hacia API Management.
Resultados de la POC
Sobre cinco especificaciones de dominios variados, el dry-run cerró en build exitoso y sin parches pendientes tras incorporar los arreglos no disruptivos. El mensaje clave para negocio e integraciones: impacto cero en el contrato — sin renombrar operationId ni parámetros que ya consumen clientes.
Por qué esto es “código como infraestructura”
Estandarización masiva — una vez construida la “fábrica” de recetas, el esfuerzo marginal de pasar de cinco APIs al resto del inventario es el mismo proceso, repetible y gobernado.
Menos error humano — desaparecen typos en metadatos y configuraciones repetitivas.
Gobernanza y seguridad inyectadas — adherencia al estándar organizacional y detección temprana de riesgos arquitectónicos pre migración.
Hacia el despliegue completo del track
El roadmap que cerramos tiene tres fases: extender recetas y auditorías a más ítems del checklist; planificar despliegue de políticas en APIM (global, producto o API) con validaciones previas al cutover; y ejecución masiva del pipeline sobre todo el inventario en entorno controlado.
OpenRewrite no es el único actor (el gateway y las plantillas de política son igual de críticos), pero es el pegamento declarativo que hace viable la parte del contrato a escala.
¿Tu organización separa ya el “qué expone el OpenAPI” del “cómo se comporta en el borde”? ¿Cómo lo versionan?
Enjoy!
José Díaz
