fnematov/scramble-laravel-data

Automatic generation of API documentation for Laravel applications.

1.0.1 2026-08-28 04:55 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• myclabs/deep-copy: ^1.12
• nikic/php-parser: ^5.0
• phpstan/phpdoc-parser: ^1.0|^2.0
• spatie/laravel-data: ^4.0
• spatie/laravel-package-tools: ^1.9.2

Requires (Dev)

• larastan/larastan: ^3.3
• laravel/pint: ^v1.1.0
• nunomaduro/collision: ^7.0|^8.0
• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• pestphp/pest: ^2.34|^3.7|^4.4
• pestphp/pest-plugin-laravel: ^2.3|^3.1|^4.1
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^10.5|^11.5.3|^12.5.12
• spatie/laravel-permission: ^6.10|^7.2
• spatie/pest-plugin-snapshots: ^2.1

MIT

• Roman Lytvynenko

• documentation
• laravel
• openapi

Published on Packagist.org on 2026-08-28 04:59 UTC

README

Scramble for Laravel Data

A fork of dedoc/scramble that teaches Scramble to understand spatie/laravel-data Data classes.

Scramble generates OpenAPI 3.1.0 documentation for a Laravel application straight from your code, without asking you to write PHPDoc annotations. Upstream Scramble infers types from plain PHP, Eloquent models and API resources — but it does not know about Spatie\LaravelData\Data, so a Data class used as a request payload or returned from a controller ends up documented as a bare object. This fork fills that gap.

Heads up: this fork ships under the Fnematov\ScrambleLaravelData\ namespace, not Dedoc\Scramble\. It registers the same scramble config file, views and /docs/api routes as upstream, so install one or the other — not both.

Installation

composer require fnematov/scramble-laravel-data

The service provider is auto-discovered. After install you have two routes:

• /docs/api — UI viewer for your documentation
• /docs/api.json — the OpenAPI document describing your API

By default these are available only in the local environment. You can change that by defining the viewApiDocs gate.

What this fork adds

Data classes as request payloads

Type-hint a Data class on a controller action and its public properties are documented as the request body — or as query parameters for GET, HEAD and DELETE routes.

use Spatie\LaravelData\Attributes\Validation\{Email, Max};
use Spatie\LaravelData\Data;

class CreateUserData extends Data
{
    public function __construct(
        public string $name,
        #[Email]
        public string $email,
        #[Max(500)]
        public ?string $bio = null,
    ) {}
}

public function store(CreateUserData $data): UserData
{
    // ...
}

A property is marked required unless its type allows null or it declares a default value.

If the Data class also defines rules(), only one schema is produced — the extractor tells Scramble's form-request path to stand down, so you no longer get a duplicated request body.

Validation attributes become schema constraints

Spatie validation attributes are translated into real OpenAPI keywords instead of being dropped:

Attribute	OpenAPI output
#[Email]	format: email
#[Url]	format: uri
#[Uuid] / #[Ulid]	format: uuid / format: ulid
#[IP], #[IPv4]	format: ipv4
#[IPv6]	format: ipv6
#[DateFormat('Y-m-d')]	format: date
#[DateFormat('Y-m-d H:i:s')]	format: date-time
#[Min], #[Max], #[Size], #[Between]	minLength/maxLength, minimum/maximum or minItems/maxItems, picked from the property type
#[Regex]	pattern, with the PHP delimiters stripped
#[Nullable]	nullable type

List and paginated responses

Add the HasPaginatedResponse trait to a Data class to return documented collection responses:

use Fnematov\ScrambleLaravelData\Support\LaravelData\HasPaginatedResponse;
use Spatie\LaravelData\Data;

class UserData extends Data
{
    use HasPaginatedResponse;

    public function __construct(
        public int $id,
        public string $name,
    ) {}
}

public function index()
{
    return UserData::paginated(User::query()->paginate());
}

public function all()
{
    return UserData::list(User::all());
}

paginated() documents and returns:

{
  "items": [{ "id": 1, "name": "Ada" }],
  "totalCount": 42,
  "totalPages": 3,
  "currentPage": 1,
  "perPage": 15,
  "hasMorePages": true
}

list() documents and returns { "items": [...] }. The item schema is a $ref to the Data class, so it is not inlined at every call site.

Property types Scramble now resolves

• Backed enums — rendered as an enum of their values, including arrays of enums (Status[]), which previously collapsed to array[string]
• UploadedFile and UploadedFile[] — string with format: binary and contentMediaType: application/octet-stream
• Array shapes from @var docblocks — array{name: string, age?: int} becomes a real object schema with the right required keys, instead of array[string]
• Collections — array<string, T>, T[], DataCollection<T> and Collection<T>
• Self-referencing Data classes — emitted as a $ref rather than nesting forever

Documentation

Everything not listed above behaves exactly like upstream Scramble, whose full documentation lives at scramble.dedoc.co.

Credits

Scramble is built by Roman Lytvynenko and the dedoc team. This fork only adds the spatie/laravel-data layer on top; all credit for the documentation generator itself belongs upstream.

License

MIT. See LICENSE.md.