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

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

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

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

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