# 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**](https://docs.openrewrite.org/) 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. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQGH4z45I47BqQ/article-inline_image-shrink_1500_2232/B4EZ3b5lieJQAY-/0/1777510801831?e=1779321600&v=beta&t=Lvw0YgdaXUZPSsDVL1ssmuA9n1CPpTQK1P-cvMonWoQ align="center") ### **Bifurcar contrato y ejecución** La estrategia separa dos mundos que a menudo se mezclan y generan deuda: 1. **Especificación OpenAPI (YAML)** — metadatos, forma del contrato, alineación a lineamientos de gobierno (por ejemplo criterios tipo **DIS02/DIS03** en nuestro marco). 2. **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. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQFefr3RznWUjA/article-inline_image-shrink_1500_2232/B4EZ3b5xQPGYAY-/0/1777510849370?e=1779321600&v=beta&t=JefrWvHpLA2vZxfNk1LjyYhHpaJY5h7J77s0vJQap_U align="center") ### **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](http://info.contact), externalDocs) sin pisar lo que ya definió el equipo, con parámetros del estilo acceptTheirs: true donde aplica. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQFuhR9EbaGRog/article-inline_image-shrink_1500_2232/B4EZ3b67_xJMAU-/0/1777511155791?e=1779321600&v=beta&t=nNubJcsxTe5hbwmj-ZSlVkmsyCj6eD8eSflVyvaIYYU align="center") ### **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](http://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. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQHPJ2fBRRDwyw/article-inline_image-shrink_1000_1488/B4EZ3b8U0DIMAQ-/0/1777511519024?e=1779321600&v=beta&t=VJ6X3c9hVrTIcTIM0-Ztebn_D_uq3fXFRmPDD9qfFiE align="center") ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQGU0jAxL_wgQw/article-inline_image-shrink_1000_1488/B4EZ3b8b93JkAQ-/0/1777511548340?e=1779321600&v=beta&t=R1DRnKZ8WoB4RbiF6_Fe4ug4OCRrVHONCDA8qyGS7Xk align="center") ### **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. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQGKEIL8CIQ0kQ/article-inline_image-shrink_1000_1488/B4EZ3b8kPqK0AU-/0/1777511582581?e=1779321600&v=beta&t=koSOjqSUoNmznj_Zq91S7chwyn9v5bkqbmVp1Ra3YvQ align="center") ### **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. ![Contenido del artículo](https://media.licdn.com/dms/image/v2/D4E12AQGN5SSQH8DZQQ/article-inline_image-shrink_1000_1488/B4EZ3b9EWRJMAQ-/0/1777511713734?e=1779321600&v=beta&t=1U2ejrhGRyNesbvg705CG6Sol4Qb4RclLwRtm6JLrn0 align="center") * * * ### **Por qué esto es “código como infraestructura”** 1. **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. 2. **Menos error humano** — desaparecen typos en metadatos y configuraciones repetitivas. 3. **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