ScrambleSpatieQueryBuilder

Automatically document Spatie Laravel Query Builder filters, sorts, includes, and fields in Dedoc Scramble OpenAPI docs.

No PHPDoc annotations required — the package inspects your controller code and registers Scramble extensions automatically.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• dedoc/scramble ^0.13
• spatie/laravel-query-builder ^7.0

Installation

composer require lokiwich/scramble-spatie-query-builder

The service provider auto-registers four Scramble operation transformers. You do not need to add anything to config/scramble.php.

Usage

Use Spatie Query Builder in your controllers as usual:

use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

public function index()
{
    $users = QueryBuilder::for(User::class)
        ->allowedFields(['id', 'name', 'email'])
        ->allowedFilters([
            'name',
            AllowedFilter::exact('email'),
            AllowedFilter::groupOr('q', [
                AllowedFilter::partial('name'),
                AllowedFilter::partial('email'),
            ]),
        ])
        ->allowedIncludes('posts', 'roles')
        ->allowedSorts('name', 'created_at')
        ->paginate();

    return UserResource::collection($users);
}

Scramble will document query parameters using names from config/query-builder.php (filter, sort, include, fields). When scramble.flatten_deep_query_parameters is true (default), filters and fields use bracket notation (filter[name], fields[users]).

Filter parameters are documented only when you call allowedFilters() explicitly, matching Spatie's filtering rules. Supported definitions include variadic strings, arrays, AllowedFilter::partial / exact / beginsWith / endsWith / operator / scope / belongsTo / callback / custom / trashed, filter aliases, groupOr / groupAnd, and chained ignore(), nullable(), and default().

Customization

Hook into any extension before parameters are added:

use Lokiwich\ScrambleSpatieQueryBuilder\Extensions\DocumentsAllowedIncludes;
use Dedoc\Scramble\Support\Generator\Operation;
use Dedoc\Scramble\Support\Generator\Parameter;

DocumentsAllowedIncludes::hook(function (Operation $operation, Parameter $parameter) {
    $parameter->description('Eager-load related resources');
});

Return true from the hook to prevent the parameter from being added.

Testing

composer install
composer test

Tests use Orchestra Testbench and Scramble's Generator directly — no host application required.

License

MIT © lokiwich