{"canonical_url":"https://engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","content_markdown":"# Перенесла API на Huma v2 зі 100% відповідністю\n\nПеренесла HTTP API з Fiber на Huma v2 — 649 шляхів і 760 операцій — досягнувши та втримавши 100% відповідність між маршрутами, які реєструє сервер, і описом OpenAPI, який він публікує.\n\n2025\n\n**Ситуація.** API починався на Fiber, а валідацію запитів писали вручну, для кожного ендпоінта окремо. Це нормально, коли ендпоінтів жменька. Коли ж поверхня API розростається, це вже не нормально: валідація, написана вручну, перетворюється на податок на супровід, а дрібні неузгодженості непомітно просочуються, бо перевірки кожного ендпоінта — окрема неповторна сніжинка. До того ж єдиного опису форми API не було ніде.\n\n**Завдання.** Мета — щоб валідація випливала з типів, а не з перевірок, написаних вручну, і щоб з'явився справжній контракт, який описує API, — і все це без зупинки на те, щоб переписати все одним махом.\n\n**Дія.** HTTP‑рівень перенесено на Huma v2 поверх Fiber, тож наявний рантайм зберігся. Кожен ендпоінт отримує вхідні та вихідні структури, а Huma генерує з цих типів валідацію запитів і модель відповідей. Опис OpenAPI при цьому з'являється задарма, тобто документація встигає за кодом, а не застаріває у вікі. Усе нове писалося під Huma, наявні маршрути перенесено, і на чистому Fiber лишилося рівно два ендпоінти — WebSocket‑ендпоінти, де справді потрібен сам сокет, а модель запиту й відповіді Huma не пасує. З часом це виросло до 649 шляхів із 760 операціями, а перевірка в CI порівнює маршрути, які сервер реєструє насправді, з тими, що їх оголошує опис OpenAPI. Відповідність — 100%, і такою вона й лишається, бо через неописаний маршрут збірка падає.\n\n**Результат.** Нові ендпоінти отримують валідацію та актуальну документацію без жодних додаткових зусиль, а цілий клас помилок в обробці запитів — отих «ой, а тут ми забули перевірити це поле» — зник. Коли операцій 760, API на практиці читають лише через опис, тож гарантія його повноти важить більше, ніж тоді, коли їх було п'ятдесят. Типізований контракт зробив API водночас безпечнішим для змін і простішим для передачі іншій людині, адже типи самі кажуть, чого чекає ендпоінт.\n\n---\n\n- Роль: Backend‑інженер\n- Категорії: [Архітектура платформи](https://software.engineer.company/uk/categories/platform-architecture/), [Backend‑розробка](https://software.engineer.company/uk/categories/backend/), [API та інтеграції](https://software.engineer.company/uk/categories/api/), [Міграції та модернізація](https://software.engineer.company/uk/categories/migration/), [Тестування та QA](https://software.engineer.company/uk/categories/testing/), [Документація](https://software.engineer.company/uk/categories/documentation/)\n- Послуги: [Архітектура платформи та рішень](https://software.engineer.company/uk/services/platform-architecture/), [Backend- та API‑розробка](https://software.engineer.company/uk/services/backend-development/), [Інструменти ШІ‑агентів та MCP‑сервери](https://software.engineer.company/uk/services/ai-tools/), [Технічна документація](https://software.engineer.company/uk/services/technical-documentation/)\n\n\u003chttps://engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/\u003e\n","date_modified":"2026-10-21T16:38:05Z","description":"Нові ендпоінти отримують валідацію та актуальну документацію без жодних додаткових зусиль, а цілий клас помилок в обробці запитів — отих «ой, а тут ми забули…","formats":{"gemtext":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.gmi","gopher":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/gophermap","html":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","json":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.json","markdown":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.md","pdf":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.pdf"},"kind":"page","language":"uk","title":"Перенесла API на Huma v2 зі 100% відповідністю","url":"https://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","version":1}