Laravel Actions

Zero-configuration OpenAPI documentation for Loris Leiva’s Laravel Actions pattern.

Overview

Laravel Actions (lorisleiva/laravel-actions) organizes application business logic into reusable action classes that can be executed as controllers, jobs, listeners, or commands.

Geni natively understands the Laravel Actions pattern:

• Recognizes routes registered directly using an Action class name.
• Accurately resolves asController() or handle() as the execution method.
• Extracts validation rules from an action’s rules() method.
• Documents automatic 403 Forbidden responses from an action’s authorize() method.
• Derives human-readable operation summaries from the Action class name.

Routing Resolution

In Laravel Actions, single-action routes are commonly defined as:

routes/api.php

use App\Actions\CreateUser;
use App\Actions\PublishArticle;
use Illuminate\Support\Facades\Route;

Route::post('/users', CreateUser::class);
Route::post('/articles/{article}/publish', PublishArticle::class);

When Geni discovers these routes:

1. It inspects the AST of the target class.
2. It detects the Lorisleiva\Actions\Concerns\AsAction trait or method presence.
3. It selects asController() (preferred) or handle() (fallback) to inspect for controller behavior.

Validation Extraction

When an Action class defines a rules() method or accepts an ActionRequest:

namespace App\Actions;

use Lorisleiva\Actions\ActionRequest;
use Lorisleiva\Actions\Concerns\AsAction;

class CreateUser
{
    use AsAction;

    public function authorize(ActionRequest $request): bool
    {
        return $request->user()->can('create-users');
    }

    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'unique:users,email'],
        ];
    }

    public function asController(ActionRequest $request)
    {
        // ...
    }
}

Geni statically parses the rules() method:

• Request body schema is generated with name and email properties.
• Both fields are marked as required.
• String constraints and email formats are automatically applied.

Automatic 403 Response

When an action class defines an authorize() method containing non-trivial logic (not merely return true;), Geni automatically documents a 403 Forbidden response:

"403": {
  "description": "This action is unauthorized."
}

Operation Summary Derivation

When no explicit @summary or #[Endpoint] title is present on an action method, Geni derives a clean, human-readable summary from the action class name:

• CreateUser -> "Create user"
• PublishArticleAction -> "Publish article"
• ExportMonthlyReport -> "Export monthly report"