Annotations reference

1
use Dedoc\Scramble\Attributes\ExcludeRouteFromDocs;
2

3
class UserController extends Controller
4
{
5
    #[ExcludeRouteFromDocs]
6
    public function internalMethod()
7
    {
8
        // This route will not appear in the documentation
9
    }
10
}

1
use Dedoc\Scramble\Attributes\ExcludeAllRoutesFromDocs;
2

3
#[ExcludeAllRoutesFromDocs]
4
class UserController extends Controller
5
{
6
    public function store()
7
    {
8
        // This route will not appear in the documentation
9
    }
10

11
    public function update()
12
    {
13
        // This route will not appear in the documentation
14
    }
15
}

1
use Dedoc\Scramble\Attributes\QueryParameter;
2

3
class TodoItemsController
4
{
5
    #[QueryParameter('per_page', description: 'Number of items per page.', type: 'int', default: 10, example: 20)]
6
    public function index()
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\HeaderParameter;
2

3
class ApiController extends Controller
4
{
5
    #[HeaderParameter('X-API-Key', description: 'API key for authentication.', type: 'string', required: true)]
6
    public function index()
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\CookieParameter;
2

3
class ApiController extends Controller
4
{
5
    #[CookieParameter('session_id', description: 'Session identifier.', type: 'string')]
6
    public function index()
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\PathParameter;
2

3
class TodoItemsController
4
{
5
    #[PathParameter('todoItem', description: 'Todo item being updated', type: 'string', format: 'uuid', example: '550e8400-e29b-41d4-a716-446655440000')]
6
    public function update(Request $request, TodoItem $todoItem)
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\BodyParameter;
2

3
class TodoItemsController
4
{
5
    #[BodyParameter('title', description: 'The title of the todo item.', type: 'string', required: true)]
6
    public function store(Request $request)
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\Header;
2

3
class SampleController
4
{
5
    #[Header('X-RateLimit-Limit', 'The amount of requests allowed per minute', type: 'int')]
6
    public function __invoke(Request $request)
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\Response;
2

3
class SampleController
4
{
5
    #[Response('The sample created before')]
6
    public function __invoke(Request $request)
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\Response;
2

3
class SampleController
4
{
5
    #[Response(201, 'Created item ID', type: 'array{id: int}')]
6
    public function __invoke(Request $request)
7
    {
8
        // ...
9
    }
10
}

1
use Dedoc\Scramble\Attributes\QueryParameter;
2
use Dedoc\Scramble\Attributes\Example;
3

4
class TodoItemsController
5
{
6
    #[QueryParameter(
7
        'status',
8
        description: 'Filter todos by status.',
9
        examples: [
10
            'active' => new Example('active', summary: 'Active todos', description: 'Returns only active todo items'),
11
            'completed' => new Example('completed', summary: 'Completed todos', description: 'Returns only completed todo items'),
12
        ]
13
    )]
14
    public function index()
15
    {
16
        // ...
17
    }
18
}

1
use Dedoc\Scramble\Attributes\SchemaName;
2

3
#[SchemaName('User')]
4
class UserResource extends JsonResource
5
{
6
    // ...
7
}

1
use Dedoc\Scramble\Attributes\Group;
2

3
#[Group('Todo Items API')]
4
class TodoItemsController
5
{
6
    // ...
7
}

1
use Dedoc\Scramble\Attributes\Group;
2

3
#[Group('Todo Items API', weight: 1)]
4
class TodoItemsController
5
{
6
    // ...
7
}
8

9
#[Group('Todos', weight: 0)]
10
class TodosController
11
{
12
    // ...
13
}

1
class OldController extends Controller
2
{
3
    /**
4
     * @deprecated
5
     */
6
    public function store(Request $request)
7
    {
8
        // This route will be marked as deprecated
9
    }
10
}

1
use Illuminate\Http\Resources\Json\JsonResource;
2

3
class UserResource extends JsonResource
4
{
5
    public function toArray($request)
6
    {
7
        return [
8
            /** @deprecated */
9
            'name' => $this->name,
10
        ];
11
    }
12
}

1
class UsersController extends Controller
2
{
3
    /**
4
     * @deprecated Deprecated since version 1.0.0.
5
     */
6
    public function store(Request $request) {}
7
}

1
/**
2
 * @deprecated
3
 */
4
class OldController extends Controller
5
{
6
    /**
7
     * @notDeprecated
8
     */
9
    public function stillActiveMethod()
10
    {
11
        // This route will not be marked as deprecated even though the controller is
12
    }
13
}

1
use Illuminate\Http\Resources\Json\JsonResource;
2

3
class UserResource extends JsonResource
4
{
5
    public function toArray($request)
6
    {
7
        return [
8
            /** @var string[] */
9
            'tags' => $this->tags,
10
        ];
11
    }
12
}

1
use Spatie\LaravelData\Data;
2

3
class UserData extends Data
4
{
5
    public function __construct(
6
        /**
7
         * @var string[] $tags
8
         */
9
        public array $tags,
10
    ) {}
11
}

1
use Illuminate\Http\Resources\Json\JsonResource;
2

3
class UserResource extends JsonResource
4
{
5
    public function toArray($request)
6
    {
7
        return [
8
            /**
9
             * @example "user@bestapi.dev"
10
             */
11
            'email' => $this->email,
12
        ];
13
    }
14
}

1
use Spatie\LaravelData\Data;
2

3
class UserData extends Data
4
{
5
    public function __construct(
6
        /**
7
         * @example "user@bestapi.dev"
8
         */
9
        public string $email,
10
    ) {}
11
}

1
use Illuminate\Http\Resources\Json\JsonResource;
2

3
class UserResource extends JsonResource
4
{
5
    public function toArray($request)
6
    {
7
        return [
8
            /** @format email */
9
            'email' => $this->email,
10
        ];
11
    }
12
}

1
use Spatie\LaravelData\Data;
2

3
class UserData extends Data
4
{
5
    public function __construct(
6
        /**
7
         * @format email
8
         */
9
        public string $email,
10
    ) {}
11
}

1
use Illuminate\Http\Resources\Json\JsonResource;
2

3
class UserResource extends JsonResource
4
{
5
    public function toArray($request)
6
    {
7
        return [
8
            /** @default "active" */
9
            'status' => $this->status,
10
        ];
11
    }
12
}

1
use Spatie\LaravelData\Data;
2

3
class UserData extends Data
4
{
5
    public function __construct(
6
        /**
7
         * @default "active"
8
         */
9
        public string $status,
10
    ) {}
11
}

1
public function store(Request $request)
2
{
3
    $request->validate([
4
        /** @query */
5
        'per_page' => ['integer'],
6
    ]);
7
    // ...
8
}

1
public function store(Request $request)
2
{
3
    $request->validate([
4
        /** @ignoreParam */
5
        'foo' => ['string'],
6
    ]);
7
}

1
use App\Models\TodoItem;
2
use App\Http\Resources\TodoItemResource;
3

4
class TodoItemsController
5
{
6
    /**
7
     * @response TodoItemResource
8
     */
9
    public function update(Request $request, TodoItem $item)
10
    {
11
        return new TodoItemResource($item);
12
    }
13
}

1
public function create(Request $request)
2
{
3
    /**
4
     * A user resource.
5
     *
6
     * @status 201
7
     * @body User
8
     */
9
    return User::create($request->only(['email']));
10
}

1
public function create(Request $request)
2
{
3
    /**
4
     * A user resource.
5
     *
6
     * @status 201
7
     * @body User
8
     */
9
    return User::create($request->only(['email']));
10
}

1
class DownloadMediaController
2
{
3
    /**
4
     * @operationId getMediaItem
5
     */
6
    public function show(Media $mediaItem)
7
    {
8
        return $mediaItem;
9
    }
10
}

1
class UploadMediaController
2
{
3
    /**
4
     * @requestMediaType multipart/form-data
5
     */
6
    public function store(Request $request)
7
    {
8
        // ...
9
    }
10
}

1
/**
2
 * @tags Todos, Items, API
3
 */
4
class TodoItemsController
5
{
6
    // All endpoints in this controller will have these tags
7
}