Code-first - спершу пишеться код, специфікація генерується з нього (атрибутами, аналізом коду):
контролери й ресурси Laravel → Scramble/Scribe → openapi.json → документація
Design-first - спершу пишеться специфікація (контракт), її обговорюють і погоджують, а потім за нею пишуть код і клієнтів:
openapi.yaml (рев'ю) → моки для фронтенду → реалізація бекенду → перевірка відповідності
Переваги code-first:
- специфікація не розходиться з кодом - вона з нього й береться;
- швидкий старт, мало додаткової роботи;
- зручно для невеликих команд, де бекенд і фронтенд пишуть ті самі люди.
Недоліки code-first:
- дизайн API формується реалізацією: назви полів і структура відповідей відображають внутрішню модель (колонки таблиць), а не потреби клієнтів;
- обговорити API можна лише після того, як його написано;
- генератор бачить не все: деталі на кшталт можливих помилок чи прикладів доводиться доповнювати.
Переваги design-first:
- контракт - до коду: фронтенд, мобільна команда й партнери погоджують API заздалегідь і працюють паралельно з моками;
- кращий дизайн: API проєктують з боку споживача, з рев'ю, як код;
- генерація серверних заготовок і валідація запитів за специфікацією.
Недоліки design-first:
- специфікацію треба підтримувати вручну - і перевіряти, що реалізація їй відповідає (тести контракту, валідація відповідей у тестах), інакше вона застаріває;
- більше процесу й інструментів.
Що обирають на практиці:
- внутрішнє API одного продукту (Laravel + SPA однієї команди) - code-first зі Scramble: мінімум зусиль, завжди актуально;
- публічне API, партнерські інтеграції, кілька команд-споживачів - design-first або гібрид: дизайн погоджується в специфікації, а згенерована з коду специфікація порівнюється з погодженою в CI;
- будь-який підхід виграє від лінтингу специфікації і перевірки змін, що ламають клієнтів, у CI.
Докладніше в документації: Документація OpenAPI для початківців
