Документация API через Scramble

Если установлен Scramble (dedoc/scramble 0.13.40 или новее), пакет документирует параметры запроса definitions API. Ничего регистрировать не нужно.

Что документируется

Действие документируется, если вызывает UserQuery::for(...) или Query::fromDefinition(new UserQuery(...)):

• fields[<key>] для типа корня, каждого типа вложенного определения, каждого типа модели morphTo и каждой связи без определения, с разрешёнными полями;
• include со всеми именами подгрузок связей, включая агрегаты;
• filter[<name>] с типом фильтра (integer, number, boolean, date, date-time, значения enum) и его значением по умолчанию, а также filter[<name>][<operator>] для каждого другого разрешённого оператора;
• sort со всеми именами в обоих направлениях и сортировками по умолчанию;
• page и per_page с максимальным размером страницы, если определение использует пагинацию;
• ответ 422 InvalidQueryParameters.

Имена и разделитель берутся из конфига query-builder. Когда действие возвращает JsonApiResource, эти параметры заменяют include и fields[...], которые Scramble выводит из ресурса.

Запросы, построенные в другом месте

Если запрос строится в сервисе или репозитории, укажите определение на действии:

use MyProgs\QueryBuilder\Scramble\DocumentsQuery;

#[DocumentsQuery(UserQuery::class)]
public function index(UserService $users)
{
    return $users->list();
}

Что не документируется

• разовый Query::for(User::class) без класса определения;
• поля, фильтры и сортировки, добавленные цепочкой после UserQuery::for();
• spatie-совместимый QueryBuilder.

Определение, которое не удаётся построить (например, с неизвестной связью), попадает в диагностику Scramble, а маршрут документируется без этих параметров.

Несколько API

API, зарегистрированные через Scramble::registerApi(), тоже получают эти параметры. Для API, настроенного с нуля, вызовите QueryBuilderScramble::register(Scramble::configure('v2')). Чтобы отключить документирование, вызовите QueryBuilderScramble::disable() в сервис-провайдере.