Перенесла API на Huma v2 зі 100% відповідністю
Перенесла HTTP API з Fiber на Huma v2 — 649 шляхів і 760 операцій — досягнувши та втримавши 100% відповідність між маршрутами, які реєструє сервер, і описом OpenAPI, який він публікує.
Роботу виконано: 2025
760 операцій API перенесено, а опис лишився правдивим
Ситуація. API починався на Fiber, а валідацію запитів писали вручну, для кожного ендпоінта окремо. Це нормально, коли ендпоінтів жменька. Коли ж поверхня API розростається, це вже не нормально: валідація, написана вручну, перетворюється на податок на супровід, а дрібні неузгодженості непомітно просочуються, бо перевірки кожного ендпоінта — окрема неповторна сніжинка. До того ж єдиного опису форми API не було ніде.
Завдання. Мета — щоб валідація випливала з типів, а не з перевірок, написаних вручну, і щоб з’явився справжній контракт, який описує API, — і все це без зупинки на те, щоб переписати все одним махом.
Дія. HTTP‑рівень перенесено на Huma v2 поверх Fiber, тож наявний рантайм зберігся. Кожен ендпоінт отримує вхідні та вихідні структури, а Huma генерує з цих типів валідацію запитів і модель відповідей. Опис OpenAPI при цьому з’являється задарма, тобто документація встигає за кодом, а не застаріває у вікі. Усе нове писалося під Huma, наявні маршрути перенесено, і на чистому Fiber лишилося рівно два ендпоінти — WebSocket‑ендпоінти, де справді потрібен сам сокет, а модель запиту й відповіді Huma не пасує. З часом це виросло до 649 шляхів із 760 операціями, а перевірка в CI порівнює маршрути, які сервер реєструє насправді, з тими, що їх оголошує опис OpenAPI. Відповідність — 100%, і такою вона й лишається, бо через неописаний маршрут збірка падає.
Результат. Нові ендпоінти отримують валідацію та актуальну документацію без жодних додаткових зусиль, а цілий клас помилок в обробці запитів — отих «ой, а тут ми забули перевірити це поле» — зник. Коли операцій 760, API на практиці читають лише через опис, тож гарантія його повноти важить більше, ніж тоді, коли їх було п’ятдесят. Типізований контракт зробив API водночас безпечнішим для змін і простішим для передачі іншій людині, адже типи самі кажуть, чого чекає ендпоінт.

Фото: music4life / Pixabay 
Фото: cocoparisienne / Pixabay
Застосуйте цей досвід у своєму проєкті
Використайте «Перенесла API на Huma v2 зі 100% відповідністю» як відправну точку для схожого завдання у вашій організації. Послуги, що стоять за цією роботою, доступні й для вашого проєкту. Передавання справ, інструкції з експлуатації і посібники, щоб ваші працівники обслуговували систему без дзвінків тому, хто її створив.
Дізнайтеся, що привело до результату
Прочитайте про ситуацію, рішення та результат цього прикладу. Ми можемо обговорити, що відповідає вашим умовам, а що потребує іншого підходу. Перенесла API на Huma v2 зі 100% відповідністю — 760 операцій API перенесено, а опис лишився правдивим
Читати далі: Доступ через Stripe та покупки в застосунку. Або перегляньте повне портфоліо.
Одна частина довшого переліку — і він увесь на цьому сайті.
Кожен запис написано однаково: ситуація, завдання, що ми зробили і що змінилося.

