Стендап Сьогодні
📢
Канал в Telegram @stendap_sogodni
🦣
@stendap_sogodni@shevtsov.me в Федиверсі
30.09.2025
Розробка обгорток для API: автоматична чи ручна
Якщо вашому продукту пощастить мати HTTP API, а потім ще й стане питання, що варто не тільки мати “голий” API, а ще й надати обгортки-SDK, то ви станете перед вибором. Або робити кожну обгортку власноруч, або згенерувати автоматично.
Звісно, щоб згенерувати автоматично, доведеться спочатку оголосити схему API. Скоріше за все, це буде схема OpenAPI, але є й інші варіанти. (Пишіть, що пробували.)
Зазвичай схема — це гарний спосіб згенерувати документацію, бо фактично документація — це і є гарно відформатована схема. Але таке ставлення до схеми закладає нам проблеми на майбутнє. Бо ми починаємо робити зміни до схеми, щоб вона мала гарний вигляд, а це не обовʼязково збігається з чистотою.
А саме, коли потім доведеться розробляти SDK для цього вашого API, може здаватися, що це дуже легко зробити — взяти, наприклад, openapi-generator, який вміє генерувати інтеграції для всіх уявних мов. Тільки як зберешся генерувати, виявиться що згенерований код не дуже красивий. Місцями — прямо гидкий.
Тоді, відповідальний програміст скаже: така якість нас не влаштовує, будемо писати власноруч. На початку вийде дійсно гарно (ну, настільки гарно, наскільки зможете написати.) Проте зовсім скоро виявиться, що підтримувати такі SDK ну дуже дорого, та ще й вони природно починають відставати від API. Користувачу SDK завжди важливіша повнота та актуальність, ніж якість коду. Тому, гадаю, в реальності ані в кого немає можливості дбайливо підтримувати ручні SDK.
Повернемося до генераторів… Виявляється, що якість згенерованого коду дуже залежить від якості схеми. Не можу поки дати ніяких конкретних рекомендацій, окрім того, щоб читати згенерований код та знаходити причини його недосконалостей. Найбільше проблем з обʼєднаними типами, тобто oneOf. Або взагалі, може API з самого початку був погано спроєктованим та незручним. Чи зручним рівно для одного внутрішнього випадку.
Як висновок… Можу порадити вкладати більшість зусиль в якість схеми та самого API, а генерацію обгорток залишити автоматизованою.