#scrambledrop: Scramble 0.7.0

January 11, 2023

Added multiple servers support, URL variables support, ability to document request body params in validation rules and more awesome improvements.

Hey Laravel community!

I am happy to announce a new version of Scramble. Scramble is Laravel API docs generator that generates doc without requiring you to write PHPDoc annotations: https://scramble.dedoc.co/introduction.

0.7.0 is out: https://github.com/dedoc/scramble/releases/tag/v0.7.0

Here are cool things I’ve added in this release.

Documenting request params

From now, you can add descriptions, examples, and override types for request params. It is useful when Scramble doesn’t generate docs properly, or when you want to be more specific in your documentation.

It works both for validate calls in your controller’s methods and for custom FormRequest classes.

To document a request param, simply add PHPDoc (or a comment) before the corresponding validation rule.

class TodoController
{
    public function store(Request $request)
    {
        $request->validate([
            /**
             * The todo item text.
             *
             * @example This is the todo item.
             */
            'body' => ['required', 'string'],
            // Whether the todo item is completed.
            'is_completed' => ['required', 'bool'],
            /**
             * The location coordinates associated with todo item.
             *
             * @var array{lat: float, long: float}
             * @example {"lat": 50.450001, "long": 30.523333}
             */
            'coordinates' => 'array',
        ]);

        // ...
    }
}

Read more about it in documentation: https://scramble.dedoc.co/usage/request#documenting-request-params-manually

Notice how coordinates are properly documented with an example and correct type, as well as other request params.

Multiple servers support

From now, you can add multiple API servers in your documentation. This will allow to try out endpoints from UI on different servers.

For example, you can have local server and a production one, to try things out.

To do so, simply define servers in Scramble config.

Defining servers in config allows to have multiple server for your API documentation.

Read more about multiple servers support in the docs: https://scramble.dedoc.co/digging-deeper/servers#multiple-servers

Server variable support

In Laravel it is possible to use some part of a domain as a parameter. Prior to 0.7.0 Scramble didn’t document this properly.

So if you have multi-tenant application and your tenants have their own domains (for example, {tenant}.yourapi.com, Scramble will document it properly.

<?php // routes/api.php

Route::domain('{subdomain}.'.config('app.domain'))->group(function () {
    Route::apiResource('todo-item', \App\Http\Controllers\TodoItemController::class)->only([
        'index',
        'store',
        'show',
        'destroy',
    ]);

// ...

You can learn more about server variable support and how to add a description to the server variable in the docs: https://scramble.dedoc.co/digging-deeper/servers#server-variables

Added more abort helpers support

Now, using abort helpers (abort, abort_if, abort_unless) will add corresponding error responses automatically. The cool thing, is that if you’ve specified a string literal as your message, Scramble will use it as an example for your documentation.

Notice the example of the message is the message the request was aborted with.

Other changes

• Improved support of other JsonResources in the resource class, added support of 3rd argument in when and whenLoaded in #87
• Fixed an issue when references couldn’t be marked as nullable in #74
• Fixed fatal error when an array item was manually documented without @var in #75
• Fixed exception caused by incorrect class const fetch on variables and other expressions handling in #86
• Improve array validation rule and falsy examples support in #89
• Fixed access to exceptions property on possibly nullable object in #95
• Fix missing phpDoc attributes on resolved type attached by PhpDocHandler when they’re attached to pending type in #96
• Fixed an exception when doctrine/dbal is not installed in #99

Thanks!

Hope you like it! If so, please share this update on Twitter (share button is on the right).

Thanks!