Обидва генерують документацію API з коду Laravel, але різними способами.
Scramble:
- статичний аналіз коду: читає маршрути, Form Request, правила валідації, API-ресурси й типи повернення - без анотацій;
- результат - специфікація OpenAPI 3.1 і веб-інтерфейс документації на її основі;
- документація оновлюється автоматично разом з кодом;
- доповнення через PHPDoc і атрибути; платна версія підтримує популярні пакети (Laravel Data, Query Builder).
Scribe:
- комбінація джерел: правила валідації з Form Request, PHPDoc-анотації (
@group,@bodyParam,@response) і, за бажанням, реальні запити до ендпойнтів у локальному оточенні, щоб отримати справжні приклади відповідей; - генерує HTML-документацію з прикладами коду кількома мовами й кнопкою «Try It Out», а також колекцію Postman і специфікацію OpenAPI;
- документація генерується командою (
php artisan scribe:generate) - статичні файли, які можна викласти будь-де.
Як обрати:
| Критерій | Scramble | Scribe |
|---|---|---|
| зусилля на старті | мінімальні | більше анотацій |
| актуальність | завжди з коду | після перегенерації |
| реальні приклади відповідей | з типів і ресурсів | можуть братися з живих запитів |
| основний артефакт | OpenAPI-специфікація | HTML-документація + Postman |
| точність при складній логіці | залежить від аналізу коду | контролюється анотаціями |
Практичні поради:
- внутрішнє API для власного фронтенду - Scramble: найменше підтримки, специфікація придатна для генерації TypeScript-клієнта;
- публічна документація з гайдами й багатьма прикладами - Scribe чи окремий інструмент документації поверх експортованої специфікації;
- реальні запити в Scribe виконуються з даними й побічними ефектами - їх налаштовують лише для безпечних ендпойнтів і окремої бази;
- у будь-якому разі експортовану специфікацію варто тримати в репозиторії й перевіряти в CI: лінтинг і пошук змін, що ламають клієнтів.
Чого не робить жоден генератор: не придумує зрозумілих описів, бізнес-правил і сценаріїв використання - ці частини пишуться людьми.