Scramble

https://scramble.dedoc.co
Admin
Scramble is an OpenAPI (Swagger) documentation generator for Laravel that automatically creates API...
Tokens:101,215
Snippets:940
Trust Score:5.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run the Boost interactive installer

Source: https://scramble.dedoc.co/ai-assisted-development

Run this Artisan command to start the interactive installer. Select the agents you use and enable both guidelines and Agent Skills when prompted. Boost detects dedoc/scramble and installs Scramble's resources. Rerun this command if you already use Boost to enable Agent Skills.

```bash
php artisan boost:install
```

--------------------------------

### Example Object for Parameters

Source: https://scramble.dedoc.co/developers/reference

Use the Example object within attributes like QueryParameter to provide detailed documentation for values, including summaries and descriptions.

```php
use Dedoc\Scramble\Attributes\QueryParameter;
use Dedoc\Scramble\Attributes\Example;

class TodoItemsController
{
    #[QueryParameter(
        'status',
        description: 'Filter todos by status.',
        examples: [
            'active' => new Example('active', summary: 'Active todos', description: 'Returns only active todo items'),
            'completed' => new Example('completed', summary: 'Completed todos', description: 'Returns only completed todo items'),
        ]
    )]
    public function index()
    {
        // ...
    }
}
```

--------------------------------

### Add description, example, and default to request parameter

Source: https://scramble.dedoc.co/usage/request

Use PHPDoc annotations to add a description, example value, and default value for a request parameter. The @example and @default annotations are recognized by Scramble.

```php
/**
 * Amount of items per page.
 * @example 50
 * @default 15
 */
$perPage = $request->integer('per_page') ?: 15;
```

--------------------------------

### Route example with auth middleware

Source: https://scramble.dedoc.co/usage/authentication

Example routes showing automatic authentication documentation: /projects requires bearer authentication and /login is documented as public. Protected routes also receive the automatic 401 Unauthenticated response.

```php
Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/projects', [ProjectController::class, 'index']);
});
```

--------------------------------

### @example annotation on a resource field

Source: https://scramble.dedoc.co/developers/reference

Use the @example annotation on a resource field to add an example to the schema.

```php
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            /**
             * @example "user@bestapi.dev"
             */
            'email' => $this->email,
        ];
    }
}
```

--------------------------------

### @example annotation on a data object property

Source: https://scramble.dedoc.co/developers/reference

Use the @example annotation on a data object property to add an example to the schema.

```php
use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        /**
         * @example "user@bestapi.dev"
         */
        public string $email,
    ) {}
}
```

--------------------------------

### Install Scramble with Composer

Source: https://scramble.dedoc.co/blog/fully-automated-api-documentation

Install Scramble in your Laravel application. This is the only required step to start generating OpenAPI documentation.

```bash
composer require dedoc/scramble
```

--------------------------------

### Example validation rules

Source: https://scramble.dedoc.co/developers/validation-rules

A basic example of validation rules for name and email fields.

```php
1
$request->validate([
2
    'name' => ['required', 'string'],
3
    'email' => ['required', 'email'],
4
]);
```

--------------------------------

### Laravel api.php with closure-based route

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-013x

Example api.php file for a fresh Laravel 12.x app after installing Scramble and running php artisan install:api. The route uses a closure and the auth:sanctum middleware, and Scramble documents it automatically.

```php
<?php


use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;


Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');

```

--------------------------------

### Manual parameter documentation with PHPDoc

Source: https://scramble.dedoc.co/usage/request

Add a PHPDoc block before a validation rule to document the parameter. Use @var to override the type and @example to provide an example value.

```php
use App\Models\Location;

class LocationsController
{
    public function update(Request $request, Location $location)
    {
        $request->validate([
            /**
             * The location coordinates.
             * @var array{lat: float, long: float}
             * @example {"lat": 50.450001, "long": 30.523333}
             */
            'coordinates' => 'array',
        ]);
    }
}
```

--------------------------------

### Example OpenAPI parameter with string serialization

Source: https://scramble.dedoc.co/usage/response

Shows how parameters are documented when using JsonApiArraySerialization::String. The description lists the available values and notes comma separation.

```json
{
    "name": "fields[appointments]",
    "in": "query",
    "description": "Available values are `title`, `description`, `status`, `created_at`. You can include multiple values by separating them with a comma.",
    "schema": {
        "type": "string"
    }
},
```

--------------------------------

### Basic GitHub Actions configuration for CI

Source: https://scramble.dedoc.co/blog/generating-and-exporting-api-spec

Basic GitHub Actions workflow to set up the Laravel application and run tests. Use this as a starting point before adding the export and commit steps.

```yaml
on: push
name: CI
jobs:
  phpunit:
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.2


    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 1
          ref: ${{ github.ref_name }}


      - name: Install composer dependencies
        run: |
          composer install --no-scripts


      - name: Prepare Laravel Application
        run: |
          cp .env.example .env
          php artisan key:generate
          php artisan migrate


      - name: Run Testsuite
        run: vendor/bin/phpunit tests/

```

--------------------------------

### Generated schema for ProjectSummary

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-01334

Example component schema generated for the ProjectSummary class. Shows the inferred object type, property types, and required list.

```json
{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "taskCount": { "type": "integer" }
  },
  "required": ["id", "name", "taskCount"]
}
```

--------------------------------

### Define resource links with toLinks method

Source: https://scramble.dedoc.co/packages/json-api

Defines resource links using the toLinks method. Each link can have a description via comments and an example via PHPDoc @example annotation. Scramble documents these as link objects per the JSON:API specification.

```php
use TiMacDonald\JsonApi\JsonApiResource;
use TiMacDonald\JsonApi\Link;

class UserResource extends JsonApiResource
{
    public function toLinks($request): array
    {
        return [
            Link::self(route('api.users.show', $this->resource)),
            // Related user
            Link::related(route('api.users.show', $this->resource->parent), ['foo' => 'bar']),
            /**
             * @example {"href":"https://api.example.com/user/1","meta":{"foo":42}}
             */
            new Link('user', 'https://example.com/user/1', ['foo' => 'bar']),
        ];
    }
}
```

--------------------------------

### Update Boost guidelines and skills

Source: https://scramble.dedoc.co/ai-assisted-development

Refreshes the generated guidelines and installed skills after updating Scramble or Laravel Boost.

```bash
php artisan boost:update
```

--------------------------------

### Customize security strategy with options

Source: https://scramble.dedoc.co/installation

Custom security strategy configuration. The example shows how to customize with a class-string and options, including middleware patterns and a bearer HTTP security scheme. This is commented out by default.

```php
'security_strategy' => [
    \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
    [
        'middleware' => ['auth', 'auth:*'],
        'scheme' => \Dedoc\Scramble\Support\Generator\SecurityScheme::http('bearer'),
    ],
],
```

--------------------------------

### Document a query parameter with QueryParameter attribute

Source: https://scramble.dedoc.co/developers/reference

Use the QueryParameter attribute to manually document a query string parameter. The example sets the name, description, type, default, and example values for the 'per_page' parameter.

```php
use Dedoc\Scramble\Attributes\QueryParameter;

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

```

--------------------------------

### Controller returning resource collection

Source: https://scramble.dedoc.co/usage/response

Example controller that returns a collection of PostResource. This is used to demonstrate automatic documentation of anonymous resource collections.

```php
use App\Http\Resources\PostResource;
use App\Models\Post;

class PostsController extends Controller
{
    public function index()
    {
        return PostResource::collection(Post::all());
    }
}
```

--------------------------------

### Laravel Data example: CompaniesJobsController, JobPayloadData, and JobData

Source: https://scramble.dedoc.co/pro

These three files form the Laravel Data example: a controller that stores a job using JobPayloadData and returns JobData, plus the two Data classes that define the request and response shapes. The JobPayloadData uses SnakeCaseMapper and a salaryRange array, while JobData adds lazy-loaded company and statistics properties.

```php
use App\Data\JobData;
use App\Data\JobPayloadData;
use App\Http\Controllers\Controller;
use App\Models\Company;
use App\Models\Job;


class CompaniesJobsController extends Controller
{
    public function store(Company $company, JobPayloadData $jobPayload)
    {
        $job = Job::make($jobPayload);


        $company->jobs()->save($job);


        return JobData::from($job);
    }
}

```

```php
use App\Enums\JobStatus;
use Spatie\LaravelData\Attributes\MapName;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Mappers\SnakeCaseMapper;


#[MapName(SnakeCaseMapper::class)]
class JobPayloadData extends Data
{
    public function __construct(
        public string $title,
        public JobStatus $status,
        /** @var array{int, int} */
        public array $salaryRange,
    )
    {
    }
}

```

```php
use App\Enums\JobStatus;
use Spatie\LaravelData\Attributes\MapName;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Lazy;
use Spatie\LaravelData\Mappers\SnakeCaseMapper;


#[MapName(SnakeCaseMapper::class)]
class JobData extends Data
{
    public function __construct(
        public int $id,
        public string $title,
        public JobStatus $status,
        /** @var array{int, int} */
        public array $salaryRange,
        public Lazy|CompanyData $company,
        /** @var array{applications: int, rejections: int, approved: int} */
        public Lazy|array $statistics,
    )
    {
    }
}

```

--------------------------------

### Define routes with server variable subdomain

Source: https://scramble.dedoc.co/usage/servers

Example routes using a domain with a {subdomain} variable. Scramble will add a server for this domain unless variables are defined in config.

```php
Route::domain('{subdomain}.application.com')->group(function () {
    Route::apiResource('todo-item', \App\Http\Controllers\TodoItemController::class)->only([
        'index',
        'store',
    ]);
});
```

--------------------------------

### Laravel middleware configuration example

Source: https://scramble.dedoc.co/blog/integrating-scramble-with-cachet

Shows Laravel's middleware configuration pattern that inspired Scramble's transformers API. It appends a middleware class to the stack using the withMiddleware method.

```php
use App\Http\Middleware\EnsureTokenIsValid;


->withMiddleware(function (Middleware $middleware) {
     $middleware->append(EnsureTokenIsValid::class);
})
```

--------------------------------

### Adding field documentation with PHPDoc annotations

Source: https://scramble.dedoc.co/usage/response

Shows how to add description, example, default value, and format annotations to resource fields. The @format date-time annotation specifies the field's format.

```php
return [
    'id' => $this->id,
    /**
     * The content of todo item, truncated.
     * @example "I need to get to..."
     * @default "..."
     */
    'content' => $this->getTruncatedContent(),
    /** @format date-time */
    'created_at' => $this->created_at->toDateTimeString(),
];
```

--------------------------------

### Controller with service call

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-01223

Example controller that calls a service method and returns a resource collection. The service method's @throws annotation is now analyzed by Scramble to document a 403 response.

```php
class ItemsController
{
    public function __construct(private ItemsRetrievalService $listService) {}


    public function __invoke(Request $request)
    {
        $this->listService->ensureCanList();


        return ItemResource::collection($this->listService->get());
    }
}
```

```php
class ItemsRetrievalService
{
    /**
     * @throws AuthorizationException
     */
    public function ensureCanList()
    {
        // ...
    }
    // ...
}
```

--------------------------------

### Expose custom UI and document paths

Source: https://scramble.dedoc.co/usage/getting-started

Use the expose method in a service provider's boot method to explicitly set the UI and document route paths.

```php
public function boot(): void
{
    Scramble::configure()
        ->expose(
            ui: '/docs/v1/api',
            document: '/docs/v1/openapi.json',
        );
}

```

--------------------------------

### Configure server variables with default and description

Source: https://scramble.dedoc.co/blog/multitenant-apis

Configures the 'tenant' server variable with a default value and description using Scramble::configure().

```php
public function boot(): void
{
    Scramble::configure()
        ->withServerVariables([
            'tenant' => new ServerVariable(
                default: 'demo',
                description: 'The tenant name.'
            )
        ]);
}
```

--------------------------------

### Register multiple API versions documentation

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-0100

Shows how to define documentation for multiple API versions (v1 and v2) with custom paths. Requires calling Scramble::ignoreDefaultRoutes() and then registering each API with its own routes.

```php
// app/Providers/AppServiceProvider.php
Scramble::ignoreDefaultRoutes();


Scramble::registerApi('v1', [
    'api_path' => 'api/v1',
]);


Scramble::registerApi('v2', [
    'api_path' => 'api/v2',
]);


// routes/web.php
Scramble::registerUiRoute(path: 'docs-v1', api: 'v1');
Scramble::registerJsonSpecificationRoute(path: 'docs-v1.json', api: 'v1');


Scramble::registerUiRoute(path: 'docs-v2', api: 'v2');
Scramble::registerJsonSpecificationRoute(path: 'docs-v2.json', api: 'v2');
```

--------------------------------

### Discover and update Boost guidelines and skills

Source: https://scramble.dedoc.co/ai-assisted-development

Checks for newly available guidelines and skills and updates them.

```bash
php artisan boost:update --discover
```

--------------------------------

### API endpoints for places and bookings

Source: https://scramble.dedoc.co/blog/fully-automated-api-documentation

Lists the RESTful endpoints for the API: GET /api/places, GET /api/bookings, POST /api/bookings, GET /api/bookings/{booking}, PUT /api/bookings/{booking}, DELETE /api/bookings/{booking}.

```http
GET    /api/places
GET    /api/bookings
POST   /api/bookings
GET    /api/bookings/{booking}
PUT    /api/bookings/{booking}
DELETE /api/bookings/{booking}
```

--------------------------------

### Define server variables with Scramble::defineServerVariables

Source: https://scramble.dedoc.co/usage/servers

Add descriptions to server variables in the boot method of a service provider. Use ServerVariable::make with default and description parameters.

```php
use Dedoc\Scramble\Scramble;
use Dedoc\Scramble\Support\Generator\ServerVariable;
use Illuminate\Routing\Route;
use Illuminate\Support\Str;


/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    Scramble::defineServerVariables([
        'subdomain' => ServerVariable::make(
            default: 'team1',
            description: 'A team on which behalf a request is being made.',
        ),
    ]);
}
```

--------------------------------

### Expose routes on subdomain with closures

Source: https://scramble.dedoc.co/usage/getting-started

Register documentation routes on a subdomain by passing closures to the ui and document parameters of the expose method.

```php
use Illuminate\Routing\Router;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Scramble::configure()
            ->expose(
                ui: fn (Router $router, $action) => $router
                    ->domain('docs.example.com')
                    ->get('docs/v1/api', $action),
                document: fn (Router $router, $action) => $router
                    ->domain('docs.example.com')
                    ->get('docs/v1/openapi.json', $action),
            );
    }
}

```

--------------------------------

### Install Laravel Boost as a dev dependency

Source: https://scramble.dedoc.co/ai-assisted-development

Run this Composer command to add Laravel Boost as a development dependency in your Laravel application. This is the first step before running the interactive installer.

```bash
composer require laravel/boost --dev
```

--------------------------------

### Configure multiple servers in scramble.servers

Source: https://scramble.dedoc.co/usage/servers

Set the 'servers' config key to an array where keys are descriptions and values are base URLs. Values are passed to the url() helper, so use relative paths or absolute URLs with protocol and path.

```php
'servers' => [
    'Local' => 'api',
    'Prod' => 'https://application.com/api',
],
```

--------------------------------

### Document attributes using property with PHPDoc

Source: https://scramble.dedoc.co/usage/response

Shows how to add PHPDoc annotations to attributes when using the $attributes property. The example documents the 'currency' attribute with default, example, and allowed values.

```php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

class InvoiceResource extends JsonApiResource
{
    public $attributes = [
        'number',
        'amount_cents',
        /**
         * Currency of the invoice (currently only USD and EUR supported).
         * @default USD
         * @example USD
         * @var 'USD'|'EUR'
         */
        'currency',
        'status',
        'created_at',
    ];
}
```

--------------------------------

### PathParameter attribute usage

Source: https://scramble.dedoc.co/developers/reference

Use the PathParameter attribute to manually document a route path parameter. The example sets the parameter name, description, type, format, and a single example value.

```php
use Dedoc\Scramble\Attributes\PathParameter;

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

--------------------------------

### Enable MiddlewareAuthSecurityStrategy in config/scramble.php

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-01334

Configuration key to enable automatic authentication documentation. It is opt-in; the default is null. Leave it disabled if you already configure security manually via extendOpenApi or afterOpenApiGenerated to avoid duplicate schemes.

```php
'security_strategy' => \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
```

--------------------------------

### Document attributes using toAttributes method with PHPDoc

Source: https://scramble.dedoc.co/usage/response

Shows how to add PHPDoc annotations to attributes when using the toAttributes method. The example documents the 'currency' attribute with default, example, and allowed values.

```php
use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

class InvoiceResource extends JsonApiResource
{
    public function toAttributes(Request $request)
    {
        return [
            'amount_cents' => $this->resource->amount_cents,
            /**
             * Currency of the invoice (currently only USD and EUR supported).
             * @default USD
             * @example USD
             * @var 'USD'|'EUR'
             */
            'currency' => $this->resource->currency,
        ];
    }
}
```

--------------------------------

### Add filter descriptions with PHPDoc annotations

Source: https://scramble.dedoc.co/packages/laravel-query-builder

Adds descriptions to filters using PHPDoc annotations. The @example annotation specifies an example value, @var specifies a type, and @format specifies a format.

```php
$companies = QueryBuilder::for(Company::class)
    ->allowedFilters(
        /**
         * The name to filter a company by. Multiple values can be passed, separated via `,` (`Nike,Tesla`)
         * @example Tesla
         */
        'name',
        /**
         * The date of the creation of the company.
         * @format date
         */
        'created_at',
    )
    ->get();
```

--------------------------------

### GET /appointments

Source: https://scramble.dedoc.co/usage/response

This snippet documents the GET /appointments endpoint that returns a paginated collection of appointment resources in JSON:API format. It includes query parameters for including relationships and sparse fieldsets, and describes the response structure.

```APIDOC
## GET /appointments

### Description
Returns a paginated collection of appointment resources in JSON:API format. Supports including related resources and sparse fieldsets.

### Method
GET

### Endpoint
/appointments

### Parameters
#### Query Parameters
- **include** (string[]) - Optional - Relationships to include. Values: bookedBy, invoices
- **fields[appointments]** (string[]) - Optional - Sparse fieldset for appointments. Values: title, description, status, created_at
- **fields[users]** (string[]) - Optional - Sparse fieldset for users. Values: name, email, created_at
- **fields[invoices]** (string[]) - Optional - Sparse fieldset for invoices. Values: number, amount_cents, currency, status, created_at

### Response
#### Success Response (200)
- **data** (AppointmentResource[]) - Required - Paginated set of appointment resources
- **links** (object) - Required - Pagination links
- **meta** (object) - Required - Metadata
- **included** (array) - Optional - Included related resources (UserResource, InvoiceResource)

#### Response Example
```json
{
  "data": [
    {
      "type": "appointments",
      "id": "1",
      "attributes": {
        "title": "string",
        "description": "string",
        "status": "string",
        "created_at": "string"
      },
      "relationships": {
        "bookedBy": {
          "data": {
            "type": "users",
            "id": "1"
          }
        },
        "invoices": {
          "data": [
            {
              "type": "invoices",
              "id": "1"
            }
          ]
        }
      },
      "links": {
        "self": "string"
      },
      "meta": {
        "readable_created_at": "string"
      }
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 15,
    "to": 1,
    "total": 1
  },
  "included": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "name": "string",
        "email": "string",
        "created_at": "string"
      }
    },
    {
      "type": "invoices",
      "id": "1",
      "attributes": {
        "number": "string",
        "amount_cents": 0,
        "currency": "string",
        "status": "string",
        "created_at": "string"
      }
    }
  ]
}
```
```

--------------------------------

### Basic HTTP authentication with SecurityScheme::http('basic')

Source: https://scramble.dedoc.co/usage/authentication

Documents a Basic HTTP authentication scheme. Requires importing the SecurityScheme class.

```php
use Dedoc\Scramble\Support\Generator\SecurityScheme;

SecurityScheme::http('basic');
```

--------------------------------

### Customize documentation URL with custom domain

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-0100

Shows how to register the documentation UI and JSON specification routes on a custom subdomain. Requires calling Scramble::ignoreDefaultRoutes() in AppServiceProvider and then defining routes in routes/web.php.

```php
// app/Providers/AppServiceProvider.php
Scramble::ignoreDefaultRoutes();


// routes/web.php
Route::domain('myapp.com', function () {
    Scramble::registerUiRoute('api-docs');
    Scramble::registerJsonSpecificationRoute('api-docs.json');
});
```

--------------------------------

### Set Scramble middleware

Source: https://scramble.dedoc.co/installation

Configures middleware for Scramble routes. The example includes 'web' and a custom RestrictedDocsAccess class.

```php
'middleware' => [
    'web',
    RestrictedDocsAccess::class,
],
```

--------------------------------

### Configure api_path with include and exclude patterns

Source: https://scramble.dedoc.co/usage/getting-started

Configure Scramble to include routes starting with 'api' and exclude specific prefixes. Without '*', patterns match complete path segments; with '*', Laravel's Str::is matching is used. A single static include becomes the API server base and is stripped from documented paths.

```php
'api_path' => [
    'include' => 'api',
    'exclude' => ['api/internal', 'api/debug'],
],
```

--------------------------------

### Manually annotate Spatie Data object properties and use it in a controller

Source: https://scramble.dedoc.co/packages/laravel-data

These two files work together: TodoData defines a Spatie Data object with manual annotations (description, @example, @var, @default) that override type inference, and TodoController converts a Todo model to TodoData in its show method. The annotations are documented in the generated OpenAPI output, with the title example and default values for content and completed.

```php
use Spatie\LaravelData\Data;

class TodoData extends Data
{
    public function __construct(
        /**
         * The title of the todo item.
         * @example Make a good-looking docs page.
         */
        public string $title,

        /**
         * Details about todo item, the amount of things to be done.
         */
        public string $content = '',

        /**
         * Whether todo item is completed.
         * @var int
         * @default 0
         */
        public $completed = false,
    ) {}
}
```

```php
use App\Data\TodoData;
use App\Models\Todo;

class TodoController extends Controller
{
    public function show(Todo $todo)
    {
        return TodoData::from($todo);
    }
}
```

--------------------------------

### Manual QueryParameter documentation

Source: https://scramble.dedoc.co/usage/request

Manually document a query parameter with description, type, default, and example. The attribute is applied to the controller method.

```php
use Dedoc\Scramble\Attributes\QueryParameter;

class TodoItemsController
{
    #[QueryParameter('per_page', description: 'Number of items per page.', type: 'int', default: 10, example: 20)]
    public function index()
    {
        // ...
    }
}
```

--------------------------------

### ComponentController with QueryBuilder and JSON:API resource

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-012x

Example controller from Cachet using Scramble to generate API docs for a JSON:API resource. Shows a show method that uses Spatie QueryBuilder to allow includes and returns a ComponentResource with a 200 status code.

```php
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);
    }
}
```

--------------------------------

### Export specification for a specific API

Source: https://scramble.dedoc.co/usage/export

Uses the `--api` option to export the specification for a registered API other than `default`, for example `v2`.

```bash
php artisan scramble:export --api=v2
```

--------------------------------

### Enabling cursor pagination in config/json-api-paginate.php

Source: https://scramble.dedoc.co/packages/laravel-json-api-paginate

Configuration file showing how to enable cursor pagination by setting 'use_cursor_pagination' to true. Scramble will document the page[cursor] query parameter when this is enabled.

```php
<?php


return [
    // ..... other config options .....


    /*
     * The key of the page[x] query string parameter for cursor.
     */
    'cursor_parameter' => 'cursor',


    /*
     * If you want to cursor pagination, set this to true.
     * This would override use_simple_pagination.
     */
    'use_cursor_pagination' => true,


    // ..... other config options .....
];
```

--------------------------------

### Configure API servers in Scramble config

Source: https://scramble.dedoc.co/installation

Example of a non-default servers configuration. When 'servers' is null, server URLs are generated from 'scramble.api_path' and 'scramble.api_domain'. When providing an array, you must specify the local server URL manually if needed. Final URLs are generated using Laravel's url helper.

```php
'servers' => [
    'Live' => 'api',
    'Prod' => 'https://scramble.dedoc.co/api',
],
```

--------------------------------

### Define NotificationData with id property

Source: https://scramble.dedoc.co/blog/scrambledrop-scramble-01316

Initial NotificationData class with only an id property. This is the starting point before adding abstract context support.

```php
namespace App\Data;


use Spatie\LaravelData\Data;


class NotificationData extends Data
{
    public function __construct(
        public string $id,
    ) {}
}
```

--------------------------------

### Register UI and JSON specification routes

Source: https://scramble.dedoc.co/usage/multiple-docs

Register the documentation UI route and the OpenAPI JSON specification route for a named API. Both methods accept a route path as the first argument and the API name as the second, returning a Route instance.

```php
// routes/web.php
Scramble::registerUiRoute(path: 'docs/v2', api: 'v2');
Scramble::registerJsonSpecificationRoute(path: 'docs/v2.json', api: 'v2');
```

--------------------------------

### PostResource class definition

Source: https://scramble.dedoc.co/usage/response

Example resource class that defines the JSON structure for a post. It uses whenLoaded to conditionally include the author relationship.

```php
use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
           'body' => $this->body,
           'author' => UserResource::make($this->whenLoaded('author')),
       ];
    }
}
```

--------------------------------

### Define filters with allowedFilters

Source: https://scramble.dedoc.co/packages/laravel-query-builder

Defines filters using the allowedFilters method on a QueryBuilder instance. The example shows filtering by 'name' and 'created_at' fields.

```php
use Spatie\QueryBuilder\QueryBuilder;
use App\Models\Company;

class CompaniesController extends Controller
{
    public function index()
    {
        $companies = QueryBuilder::for(Company::class)
            ->allowedFilters('name', 'created_at')
            ->get();

        // ...
    }
}
```

--------------------------------

### Header attribute usage

Source: https://scramble.dedoc.co/developers/reference

Use the Header attribute to manually document a response header. The example sets the header name, description, and type.

```php
use Dedoc\Scramble\Attributes\Header;

class SampleController
{
    #[Header('X-RateLimit-Limit', 'The amount of requests allowed per minute', type: 'int')]
    public function __invoke(Request $request)
    {
        // ...
    }
}
```
Tokens:
Raw