Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Чим Scribe відрізняється від Scramble і як обрати генератор документації для Laravel?

Обидва генерують документацію 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: лінтинг і пошук змін, що ламають клієнтів.

Чого не робить жоден генератор: не придумує зрозумілих описів, бізнес-правил і сценаріїв використання - ці частини пишуться людьми.

Докладніше в документації: Scribe для Laravel

Схожі питання