# API migrada a Huma v2 con paridad del 100 %

Migré la API HTTP de Fiber a Huma v2 — 649 rutas y 760 operaciones — y alcancé y mantuve una correspondencia del 100 % entre las rutas que registra el servidor y la descripción OpenAPI que publica.

2025

Situación. La API comenzó en Fiber, con validación de solicitudes escrita a mano, endpoint por endpoint. Eso funciona bien cuando solo hay unos pocos endpoints. Deja de funcionar bien cuando crece la superficie: la validación artesanal se convierte en una carga de mantenimiento y aparecen pequeñas inconsistencias porque cada endpoint tiene sus propias comprobaciones particulares. Además, no existía en ningún lugar una descripción única de la estructura de la API.

Tarea. El objetivo era que la validación procediera de los tipos en lugar de comprobaciones escritas a mano, y disponer de un contrato real que describiera la API — sin detenerse para hacer una reescritura completa de golpe.

Acción. La capa HTTP pasó a Huma v2, situado sobre Fiber, por lo que se mantuvo el entorno de ejecución existente. Cada endpoint recibe estructuras de entrada y salida, y Huma genera a partir de esos tipos la validación de solicitudes y el modelado de respuestas. De ahí sale una descripción OpenAPI sin trabajo adicional, lo que significa que la documentación sigue al código en lugar de quedar obsoleta en una wiki. Todo lo nuevo se escribió sobre Huma y las rutas existentes se fueron migrando, dejando exactamente dos endpoints directamente en Fiber — los de WebSocket, donde realmente se necesita el socket y no encaja el modelo de solicitud/respuesta de Huma. El resultado ha crecido hasta 649 rutas que abarcan 760 operaciones, con una comprobación en CI que compara las rutas que registra realmente el servidor con las que anuncia la descripción OpenAPI. La paridad es del 100 %, y se mantiene porque una ruta sin describir hace fallar la compilación.

Resultado. Los nuevos endpoints obtienen validación y documentación actualizada sin que nadie tenga que hacer trabajo adicional, y toda una clase de errores en el tratamiento de solicitudes — los del tipo «se olvidó comprobar este campo aquí» — desapareció. Con 760 operaciones, la descripción es la única forma práctica de consultar la API, por lo que la garantía de que está completa importa más que cuando había cincuenta. El contrato tipado hizo que modificar la API fuera más seguro y entregársela a otra persona fuera más sencillo, porque los tipos indican qué espera un endpoint.

Función: Ingeniera de backend
=> /es/categories/platform-architecture/ Categorías: Arquitectura de plataformas
=> /es/categories/backend/ Categorías: Ingeniería de backend
=> /es/categories/api/ Categorías: API e integración
=> /es/categories/migration/ Categorías: Migraciones y modernización
=> /es/categories/testing/ Categorías: Pruebas y control de calidad
=> /es/categories/documentation/ Categorías: Documentación
=> /es/services/platform-architecture/ Servicios: Arquitectura de plataformas y soluciones
=> /es/services/backend-development/ Servicios: Desarrollo de backend y API
=> /es/services/ai-tools/ Servicios: Herramientas para agentes de IA y servidores MCP
=> /es/services/technical-documentation/ Servicios: Documentación técnica

=> https://software.engineer.company/es/portfolio/migrated-the-api-to-huma-v2-at-100-parity/ Esta página en la web
