README

Scramble operation transformers for Laravel REST APIs — the OpenAPI documentation glue extracted from the net-tech portfolio API.

Install

composer require net-code/laravel-scramble

Pulls in dedoc/scramble and spatie/laravel-data.

What's inside

Usage

Register the transformers in a service provider's boot(). TagByNamespace is convention-first (no annotation needed), with #[ApiTag] as a per-controller override. The resolver receives the split namespace and returns the tag — here, audience-first (Admin / Billing, Client / Projects), falling back to the context name when a controller has no audience subfolder:

use Dedoc\Scramble\Scramble;
use NetCode\Scramble\DocumentDataQueryParameters;
use NetCode\Scramble\DocumentErrorResponses;
use NetCode\Scramble\TagByNamespace;

Scramble::configure()->withOperationTransformers([
    new TagByNamespace('Contexts\\', static function (array $segments): ?string {
        $context = $segments[1] ?? null;

        if ($context === null) {
            return null;
        }

        $at = array_search('Controllers', $segments, true);
        $audience = is_int($at) && isset($segments[$at + 2]) ? $segments[$at + 1] : null;

        return $audience === null ? $context : $audience.' / '.$context;
    }),
    new DocumentErrorResponses(namespacePrefix: 'Contexts\\'),
    $this->app->make(DocumentDataQueryParameters::class),
]);

Any controller can opt out of the convention: #[ApiTag('Reports')] forces its group, and #[ApiErrors(404, 409)] adds domain error responses.

License

MIT