Перенесла API на Huma v2 зі 100% відповідністю
Перенесла HTTP API з Fiber на Huma v2 — 649 шляхів і 760 операцій —
досягнувши та втримавши 100% відповідність між маршрутами, які
реєструє сервер, і описом OpenAPI, який він публікує.
2025

Ситуація. API починався на Fiber, а валідацію запитів писали вручну,
для кожного ендпоінта окремо. Це нормально, коли ендпоінтів жменька.
Коли ж поверхня API розростається, це вже не нормально: валідація,
написана вручну, перетворюється на податок на супровід, а дрібні
неузгодженості непомітно просочуються, бо перевірки кожного
ендпоінта — окрема неповторна сніжинка. До того ж єдиного опису
форми API не було ніде.

Завдання. Мета — щоб валідація випливала з типів, а не з перевірок,
написаних вручну, і щоб з'явився справжній контракт, який описує
API, — і все це без зупинки на те, щоб переписати все одним махом.

Дія. HTTP‑рівень перенесено на Huma v2 поверх Fiber, тож наявний
рантайм зберігся. Кожен ендпоінт отримує вхідні та вихідні
структури, а Huma генерує з цих типів валідацію запитів і модель
відповідей. Опис OpenAPI при цьому з'являється задарма, тобто
документація встигає за кодом, а не застаріває у вікі. Усе нове
писалося під Huma, наявні маршрути перенесено, і на чистому Fiber
лишилося рівно два ендпоінти — WebSocket‑ендпоінти, де справді
потрібен сам сокет, а модель запиту й відповіді Huma не пасує. З
часом це виросло до 649 шляхів із 760 операціями, а перевірка в CI
порівнює маршрути, які сервер реєструє насправді, з тими, що їх
оголошує опис OpenAPI. Відповідність — 100%, і такою вона й
лишається, бо через неописаний маршрут збірка падає.

Результат. Нові ендпоінти отримують валідацію та актуальну
документацію без жодних додаткових зусиль, а цілий клас помилок в
обробці запитів — отих «ой, а тут ми забули перевірити це поле» —
зник. Коли операцій 760, API на практиці читають лише через опис,
тож гарантія його повноти важить більше, ніж тоді, коли їх було
п'ятдесят. Типізований контракт зробив API водночас безпечнішим для
змін і простішим для передачі іншій людині, адже типи самі кажуть,
чого чекає ендпоінт.

Категорії:
1Архітектура платформи	/uk/categories/platform-architecture/	advisory.engineer.company	70
1Backend‑розробка	/uk/categories/backend/	advisory.engineer.company	70
1API та інтеграції	/uk/categories/api/	advisory.engineer.company	70
1Міграції та модернізація	/uk/categories/migration/	advisory.engineer.company	70
1Тестування та QA	/uk/categories/testing/	advisory.engineer.company	70
1Документація	/uk/categories/documentation/	advisory.engineer.company	70

Послуги:
1Архітектура платформи та рішень	/uk/services/platform-architecture/	advisory.engineer.company	70
1Backend- та API‑розробка	/uk/services/backend-development/	advisory.engineer.company	70
1Інструменти ШІ‑агентів та MCP‑сервери	/uk/services/ai-tools/	advisory.engineer.company	70
1Технічна документація	/uk/services/technical-documentation/	advisory.engineer.company	70

hЦя сторінка у вебі	URL:https://advisory.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/	advisory.engineer.company	70
