#scrambledrop: Scramble 0.12.x

February 6, 2025

Manual parameter documentation, transformers API, endpoint grouping and sorting, and custom schema names.

Hey Laravel community!

I’m excited to announce the v0.12.x release, which introduces long-awaited features and serves as the final stepping stone before the stable v1.x release!

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

Manually document parameters

Scramble automatically documents request parameters based on route definitions (for path parameters) and validation rules. However, you might want to add parameters manually or provide additional details for automatically documented parameters.

v0.12.x introduces five new attributes to help with this! With #[QueryParameter], #[HeaderParameter], #[CookieParameter], #[PathParameter], and #[BodyParameter], you can document parameters that aren’t automatically recognized or add more details to inferred parameters:

use App\Data\TodoData;
use App\Models\Todo;
use Dedoc\Scramble\Attributes\QueryParameter;

class TodoController extends Controller
{
    #[QueryParameter('page', description: 'The page number.', type: 'int', default: 10)]
    public function index(Request $request)
    {
        // ...
    }
}

Manually documented parameters override Scramble’s automatically inferred ones. If needed, you can disable this behavior by passing infer: false to the attribute.

Learn more in the documentation!

Group and sort endpoints

You can now easily group and sort endpoints using the #[Group] attribute! Apply it to a controller class or a specific method to define an endpoint group:

use Dedoc\Scramble\Attributes\Group;

#[Group('Places')]
class PlaceController
{
    public function index() {/* */}
    public function store() {/* */}
    public function destroy() {/* */}
}

For sorting groups, you can pass the weight argument to the attribute:

use Dedoc\Scramble\Attributes\Group;

#[Group('Places', weight: 2)]
class PlaceController {}

#[Group('Bookings', weight: 1)]
class BookingController {}

Groups are sorted by weight, with lower-weight groups appearing first.

You can learn more in the documentation!

Explicitly name schemas

When you return a JSON API resource or a model from your controller, Scramble documents it as a reusable schema in the OpenAPI document. By default, Scramble uses the class name as the schema name.

Now, you can use the #[SchemaName] attribute to define custom names for class-based schemas. This works for models, JSON API resources, enums, and Laravel Data objects.

use Dedoc\Scramble\Attributes\SchemaName;

#[SchemaName('User')]
class UserResource extends JsonResource
{
    // ...
}

Transformers API

As Scramble adoption grows, it has become clear that more extension points are needed for customizing the generated documentation.

v0.12.x introduces an experimental transformers API! This allows you to modify the document, an operation, and—soon—a schema. Unlike the existing extensions API, transformers give you much more control over execution order.

• Document transformers let you customize the OpenAPI document.
• Operation transformers let you modify individual operations.
• Schema transformers (coming soon!) will allow customization of individual schemas.

Learn more about the transformers API in the documentation.

timacdonald/json-api support

I also tagged v0.7.x of Scramble PRO.

This release includes basic support for timacdonald/json-api, a great library for building APIs that follow the JSON:API standard.

Here is an example from the real project. Cachet uses Scramble to generate its API docs reference.

Just look at how much documentation Scramble generates without any annotations!

use Cachet\Models\Component;
use Cachet\Http\Resources\Component as ComponentResource;
use Illuminate\Http\Response;
use Spatie\QueryBuilder\QueryBuilder;

class ComponentController extends Controller
{
    public const ALLOWED_INCLUDES = [
        'group',
        'incidents',
    ];

    public function show(Component $component)
    {
        $componentQuery = QueryBuilder::for($component)
            ->allowedIncludes(self::ALLOWED_INCLUDES)
            ->first();

        return ComponentResource::make($componentQuery)
            ->response()
            ->setStatusCode(Response::HTTP_OK);
    }
}

If you’re using this package, give Scramble a try!

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