#scrambledrop: Scramble 0.12.14

March 21, 2025

Enum cases documentation, support for array request bodies, and improved type inference for classes properties.

Hey Laravel community!

Since the 0.12.x initial release I’ve released many smaller releases that introduce useful features, and in this post we’ll check them all.

Scramble is a Laravel API documentation generator that creates docs without requiring PHPDoc annotations: https://scramble.dedoc.co/introduction.

Enum cases documentation

This version adds support for enum case descriptions — a long-requested and highly upvoted feature!

Now, you can add PHPDoc comments above enum cases, and Scramble will use them as enum descriptions:

enum JobStatus: string
{
    /**
     * When the job application is available.
     */
    case OPEN = 'open';

    /**
     * When the job has been closed.
     */
    case CLOSED = 'closed';
}

This will produce the following JSON schema:

{
    "title": "JobStatus",
    "type": "string",
    "enum": ["open", "closed"],
    "description": "|---|---|\n|`open`|When the job application is available.|\n..."
}

If you use OpenAPI rendering solutions that support it, you can use the x-enumDescriptions extension for case descriptions by setting scramble.enum_cases_description_strategy to extension. In this case, the generated JSON schema will look like this:

{
    "title": "JobStatus",
    "type": "string",
    "enum": ["open", "closed"],
    "x-enumDescriptions": {
        "open": "When the job application is available.",
        "closed": "When the job has been closed."
    }
}

Support for arrays in request body root

Now it is possible to provide validation rules for arrays as request body root:

$request->validate([
    '*.foo' => ['required', 'string'],
    '*.bar' => ['required', 'string'],
]);

Scramble will correctly recognize that request body is an array of objects with foo and bar properties.

Type inference improvements

Now Scramble will be able to infer types originating from typed property calls. This allows you to have a correct documentation for method calls on services you inject into your controller.

// CompanyController.php
<?php

namespace App\Http\Controllers\Api;

use App\CompanyDataFactory;
use App\Http\Controllers\Controller;
use App\Models\Company;

class CompanyController extends Controller
{
    public function __construct(
        private readonly CompanyDataFactory $companyDataFactory,
    ) {}

    /**
     * Get company.
     */
    public function show(Company $company)
    {
        return $this->companyDataFactory->createTerseCompanyData($company);
    }
}

// CompanyDataFactory.php
<?php

namespace App;

use App\Data\CompanyData;

class CompanyDataFactory
{
    public function createTerseCompanyData($model): CompanyData
    {
        return CompanyData::from($model)->only('id');
    }
}

Scramble will correctly document the response from show controller’s method 🔥

only and except support for Laravel Data

I’ve added the support for only and except methods for Laravel Data. This includes conditional only and except as well as support for onlyProperties and exceptProperties methods defined in data objects classes.

Consider the following example:

public function show(Company $company)
{
    return CompanyData::from($company)->only('id');
}

Now, Scramble will correctly document that this endpoint returns a structure containing only id property:

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        }
    },
    "required": [
        "id"
    ]
}

Thanks!

Thanks for checking this post out. If you have any questions, ideas, suggestions, feel free to drop me a line to roman@dedoc.co