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.

Categorías:
1Arquitectura de plataformas	/es/categories/platform-architecture/	engineer.company	70
1Ingeniería de backend	/es/categories/backend/	engineer.company	70
1API e integración	/es/categories/api/	engineer.company	70
1Migraciones y modernización	/es/categories/migration/	engineer.company	70
1Pruebas y control de calidad	/es/categories/testing/	engineer.company	70
1Documentación	/es/categories/documentation/	engineer.company	70

Servicios:
1Arquitectura de plataformas y soluciones	/es/services/platform-architecture/	engineer.company	70
1Desarrollo de backend y API	/es/services/backend-development/	engineer.company	70
1Herramientas para agentes de IA y servidores MCP	/es/services/ai-tools/	engineer.company	70
1Documentación técnica	/es/services/technical-documentation/	engineer.company	70

hEsta página en la web	URL:https://engineer.company/es/portfolio/migrated-the-api-to-huma-v2-at-100-parity/	engineer.company	70
