Scramble

https://github.com/dedoc/scramble
Admin
Scramble generates API documentation for Laravel projects in OpenAPI 3.1.0 format without requiring...
Tokens:329,361
Snippets:1,949
Trust Score:5.9
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Components class usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-objects.md

Registers a schema and returns a Reference to it. The example shows the fluent API for adding reusable OpenAPI objects.

```php
addSecurityScheme(string $name, SecurityScheme $securityScheme): $this
```

```php
hasSchema(string $schemaName): bool
```

```php
addSchema(string $schemaName, Schema $schema): Reference
```

```php
removeSchema(string $schemaName): void
```

```php
removeResponse(string $responseName): void
```

```php
addParameter(string $name, Parameter|Reference $parameter): Reference
```

```php
addExample(string $name, Example|Reference $example): Reference
```

```php
addRequestBody(string $name, RequestBodyObject|Reference $requestBody): Reference
```

```php
addHeader(string $name, Header|Reference $header): Reference
```

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

### security_strategy config example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/contracts-and-extensions.md

Example configuration for the security_strategy key, using the built-in MiddlewareAuthSecurityStrategy with custom middleware patterns and a bearer scheme.

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

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

### Example class constructor

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Constructor for the Example class. The dataValue and serializedValue parameters are only available in OAS 3.2.0 and later. Setters include setDataValue(mixed $dataValue): self and setSerializedValue(?string $serializedValue): self.

```php
public function __construct(
    public mixed $value = new MissingValue,
    public ?string $summary = null,
    public ?string $description = null,
    public ?string $externalValue = null,
    public mixed $dataValue = new MissingValue,     // OAS 3.2.0+
    public ?string $serializedValue = null,         // OAS 3.2.0+
) {}
```

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

### Configure AST-based analysis with buildDefinitionsUsingAstFor

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Forces AST-based analysis for the given class-string(s) or DefinitionMatcher instances. The example uses a prefix 'App\Domain\' to match classes.

```php
use Dedoc\Scramble\Scramble;

Scramble::infer()
    ->configure()
    ->buildDefinitionsUsingAstFor(['App\Domain\']);
```

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

### get(string $key, mixed $default = null)

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Performs a dot-notation lookup into the raw config array using Arr::get.

```APIDOC
## get(string $key, mixed $default = null)

### Description
Performs a dot-notation lookup into the raw config array using `Arr::get`.

### Method
get

### Signature
php
public function get(string $key, mixed $default = null)


### Parameters
- **$key** (string) - Required - The dot-notation key to look up.
- **$default** (mixed) - Optional - Default value if the key is not found.
```

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

### Example value object class definition

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Defines the Example class as a plain value object (no #[Attribute] declaration) with properties for value, summary, description, and externalValue, plus a static method toOpenApiExample.

```php
class Example
{
    public function __construct(
        public mixed $value = new MissingValue,
        public ?string $summary = null,
        public ?string $description = null,
        public ?string $externalValue = null,
    ) {}

    public static function toOpenApiExample(Example $example): OpenApiExample
}
```

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

### GET /docs/api

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Documentation for the GET /docs/api endpoint that serves the API documentation UI.

```APIDOC
## GET /docs/api

### Description
Serves the interactive API documentation UI for the default API. The response is an HTML page rendered by the configured UI renderer (Stoplight Elements or Scalar).

### Method
GET

### Endpoint
/docs/api

### Parameters
#### Query Parameters
- None

### Response
#### Success Response (200)
- **Content-Type**: text/html
- **Body**: Rendered documentation UI page

#### Error Response (403)
- **Description**: Access denied by middleware/gate

### Request Example
No request body or query parameters.

### Response Example
HTML page (not shown).
```

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

### GET /_scramble/dev-tools/devtools.js

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Serves the compiled dev-tools JavaScript bundle for the Scramble UI.

```APIDOC
## GET /_scramble/dev-tools/devtools.js

### Description
Serves the compiled dev-tools JavaScript bundle. This route is only registered when the dev tools are enabled via the scramble.dev_tools.enabled configuration.

### Method
GET

### Endpoint
/_scramble/dev-tools/devtools.js

### Parameters
#### Query Parameters
- none

### Response
#### Success Response (200)
- Content-Type: text/javascript; charset=UTF-8
- Cache-Control: no-store
- Body: the compiled dev-tools bundle

#### Error Response (404)
- Returned when the dist/devtools.js file is missing.
```

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

### Creating an OpenApi instance

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-objects.md

Shows how to create an OpenApi instance with a fluent API. The example sets the info object and includes a commented line showing how to secure the document with a bearer HTTP security scheme inside a document transformer.

```php
use Dedoc\Scramble\Support\Generator\OpenApi;
use Dedoc\Scramble\Support\Generator\InfoObject;

$openApi = OpenApi::make()
    ->setInfo(InfoObject::make('My API')->setVersion('1.0'));

// in a document transformer:
// $openApi->secure(SecurityScheme::http('bearer'));
```

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

### Configure servers in config/scramble.php

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/configuration.md

Example configuration for the 'servers' option in config/scramble.php. Maps server descriptions to API paths or URLs; final URLs are built with Laravel's url() helper.

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

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

### ObjectType usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-types.md

Shows how to build an ObjectType with properties and required fields. Uses IntegerType for 'id' and StringType with a description for 'name', then marks both as required.

```php
use Dedoc\Scramble\Support\Generator\Types\ObjectType;
use Dedoc\Scramble\Support\Generator\Types\StringType;
use Dedoc\Scramble\Support\Generator\Types\IntegerType;

$object = (new ObjectType)
    ->addProperty('id', new IntegerType)
    ->addProperty('name', (new StringType)->setDescription('Display name'))
    ->addRequired(['id', 'name']);
```

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

### MissingExample

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Extends MissingValue. Used as a sentinel for missing examples.

```APIDOC
## MissingExample

### Description
Extends MissingValue. Used as a sentinel for missing examples.

### Inheritance
`class MissingExample extends MissingValue {}`
```

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

### Register dev-tools asset route

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Registers the GET /_scramble/dev-tools/devtools.js route that serves the compiled dev-tools bundle. Returns 404 if the asset file is missing and sets Cache-Control: no-store.

```php
$router->get('_scramble/dev-tools/devtools.js', function () {
    $path = DevTools::assetPath();
    abort_unless(is_file($path), 404);
    return response()->file($path, [
        'Cache-Control' => 'no-store',
        'Content-Type' => 'text/javascript; charset=UTF-8',
    ]);
})->name('scramble.dev-tools.asset')->middleware($middleware);
```

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

### Response attribute usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Example of using the Response attribute on a controller method to document a 422 validation error response.

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

#[Response(status: 422, type: 'array{errors: array<string, string[]>}', description: 'Validation failed')]
public function store() {}
```

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

### Using GeneratorResult to handle diagnostics and write spec

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator.md

Example of generating a result, iterating over diagnostics to print errors, and writing the spec to a JSON file.

```php
$result = $generator->generate($config);

foreach ($result->diagnostics() as $diagnostic) {
    if ($diagnostic->severity() === \Dedoc\Scramble\Diagnostics\DiagnosticSeverity::Error) {
        echo $diagnostic->code().': '.$diagnostic->message().PHP_EOL;
    }
}

file_put_contents('openapi.json', json_encode($result->spec(), JSON_PRETTY_PRINT));
```

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

### GET /docs/api.json

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Retrieves the OpenAPI specification document as JSON.

```APIDOC
## GET /docs/api.json

### Description
Serves the serialized OpenAPI document as JSON, pretty-printed. The document is cached server-side according to the scramble.cache.* configuration.

### Method
GET

### Endpoint
/docs/api.json

### Parameters
#### Query Parameters
- none

### Response
#### Success Response (200)
- Content-Type: application/json
- Body: serialized OpenAPI document, JSON-pretty-printed

#### Error Response (403)
- Access denied when the RestrictedDocsAccess middleware rejects the request.

#### Response Example
```json
{
  "openapi": "3.0.0",
  "info": {},
  "paths": {}
}
```
```

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

### enforceSchema usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Example usage of enforceSchema. Registers a rule that requires schemas to be ObjectType instances, with a custom error message, ignoring paths matching '**/additionalProperties*', and recording a diagnostic instead of throwing because throw is false.

```php
use Dedoc\Scramble\Scramble;

Scramble::enforceSchema(
    fn ($schema, $path) => $schema instanceof \Dedoc\Scramble\Support\Generator\Types\ObjectType,
    fn ($schema) => 'Expected an object schema, got '.$schema::class,
    ignorePaths: ['**/additionalProperties*'],
    throw: false,
);
```

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

### AddCustomSecurityNote implementation

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/contracts-and-extensions.md

Example implementation of DocumentTransformer that appends a security note to the API description. Shows how to modify the OpenApi document in the handle method.

```php
use Dedoc\Scramble\Contracts\DocumentTransformer;
use Dedoc\Scramble\OpenApiContext;
use Dedoc\Scramble\Support\Generator\OpenApi;

class AddCustomSecurityNote implements DocumentTransformer
{
    public function handle(OpenApi $document, OpenApiContext $context)
    {
        $document->info->description .= "\n\nAll endpoints require a valid bearer token.";
    }
}
```

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

### registerUiRoute(string $path, string $api = 'default'): Route

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Registers a GET route serving the documentation UI view. The route action resolves the CacheableGenerator from the container and renders the view with spec, config and result variables. Applies the API's configured middleware.

```APIDOC
## registerUiRoute(string $path, string $api = 'default'): Route

### Description
Registers a GET route serving the documentation UI view. The route action resolves the CacheableGenerator from the container and renders the view with spec, config and result variables. Applies the API's configured middleware.

### Method
GET

### Endpoint
{path} (as registered)

### Parameters
- **$path** (string) - Required - The URL path for the UI route.
- **$api** (string) - Optional (default: 'default') - The API name.

### Response
#### Success Response
- **Route** - The registered route instance.

```

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

### Register JSON specification route

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Registers the GET /docs/api.json route that returns the OpenAPI document as JSON. The route uses the configured middleware (defaulting to RestrictedDocsAccess) and pretty-prints the response.

```php
RouteFacade::get($path, function (CacheableGenerator $generator) use ($api) {
    $config = static::getGeneratorConfig($api);

    return response()->json($generator($config), options: JSON_PRETTY_PRINT);
})->middleware($config->get('middleware', [RestrictedDocsAccess::class]));
```

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

### Api attribute usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Apply the Api attribute to a controller class to restrict it to the 'admin' API.

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

#[Api('admin')]
class AdminController
{
    public function index() {}
}
```

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

### Define viewApiDocs Gate

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Example gate definition that allows access only from 127.0.0.1 IP. Use in your application to control who can view docs.

```php
use Illuminate\Support\Facades\Gate;

Gate::define('viewApiDocs', fn ($user = null) => in_array($request->ip(), ['127.0.0.1']));
```

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

### registerJsonSpecificationRoute(string $path, string $api = 'default'): Route

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Registers a GET route returning the OpenAPI JSON document (response()->json(...), pretty-printed). Used by routes/web.php to register docs/api.json as scramble.docs.document.

```APIDOC
## registerJsonSpecificationRoute(string $path, string $api = 'default'): Route

### Description
Registers a GET route returning the OpenAPI JSON document (response()->json(...), pretty-printed). Used by routes/web.php to register docs/api.json as scramble.docs.document.

### Method
GET

### Endpoint
{path} (as registered)

### Parameters
- **$path** (string) - Required - The URL path for the JSON specification route.
- **$api** (string) - Optional (default: 'default') - The API name.

### Response
#### Success Response
- **Route** - The registered route instance.

```

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

### routes(?Closure $routeResolver = null)

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Gets or sets the route resolver. With no arguments, returns the current route resolver (custom or default). With a closure, sets it as the custom resolver.

```APIDOC
## routes(?Closure $routeResolver = null)

### Description
Calling with **no arguments** returns the current route resolver (the custom one or the default `defaultRoutesFilter(...)`). Calling with a closure sets it. The closure signature is `(Route): bool`.

### Method
routes

### Parameters
- **$routeResolver** (?Closure) - Optional - A closure that takes a `Route` and returns a bool.

### Returns
When called with no arguments, returns the current route resolver. When called with a closure, returns `$this`.
```

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

### registerUiRoute method signature

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Signature of the registerUiRoute method. Registers a GET route serving the documentation UI view. The route action resolves the CacheableGenerator from the container and renders the view with spec, config and result variables. Applies the API's configured middleware.

```php
public static function registerUiRoute(string $path, string $api = 'default'): Route
```

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

### Components Class

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-objects.md

The Components class is a registry for reusable OpenAPI objects. It provides methods to add, remove, and retrieve components like schemas, responses, parameters, examples, request bodies, headers, links, callbacks, path items, and media types.

```APIDOC
## Components Class

### Description
The `Components` class is a registry of reusable OpenAPI objects. It allows you to register and manage components such as schemas, responses, parameters, examples, request bodies, headers, links, callbacks, path items, and media types.

### Public Properties
- `$schemas` (array<string, Schema|Reference>) - Registered schemas.
- `$responses` (array<string, Response|Reference>) - Registered responses.
- `$parameters` (array<string, Parameter|Reference>) - Registered parameters.
- `$examples` (array<string, Example|Reference>) - Registered examples.
- `$requestBodies` (array<string, RequestBodyObject|Reference>) - Registered request bodies.
- `$headers` (array<string, Header|Reference>) - Registered headers.
- `$securitySchemes` (array<string, SecurityScheme|Reference>) - Registered security schemes.
- `$links` (array<string, Link|Reference>) - Registered links.
- `$callbacks` (array<string, Callback|Reference>) - Registered callbacks.
- `$pathItems` (array<string, Path|Reference>) - Registered path items.
- `$mediaTypes` (array<string, MediaType|Reference>) - Registered media types (OAS 3.2+).
- `$tempNames` (array) - Scratch space for name deduplication.

### Methods

#### addSecurityScheme
- **Signature**: `addSecurityScheme(string $name, SecurityScheme $securityScheme): $this`
- **Description**: Registers a security scheme.

#### hasSchema
- **Signature**: `hasSchema(string $schemaName): bool`
- **Description**: Checks if a schema exists.

#### addSchema
- **Signature**: `addSchema(string $schemaName, Schema $schema): Reference`
- **Description**: Registers a schema and returns a `Reference('schemas', $schemaName, $this)`.

#### removeSchema
- **Signature**: `removeSchema(string $schemaName): void`
- **Description**: Removes a schema entry.

#### removeResponse
- **Signature**: `removeResponse(string $responseName): void`
- **Description**: Removes a response entry.

#### addParameter
- **Signature**: `addParameter(string $name, Parameter|Reference $parameter): Reference`
- **Description**: Registers a parameter and returns a reference.

#### addExample
- **Signature**: `addExample(string $name, Example|Reference $example): Reference`
- **Description**: Registers an example and returns a reference.

#### addRequestBody
- **Signature**: `addRequestBody(string $name, RequestBodyObject|Reference $requestBody): Reference`
- **Description**: Registers a request body and returns a reference.

#### addHeader
- **Signature**: `addHeader(string $name, Header|Reference $header): Reference`
- **Description**: Registers a header and returns a reference.

#### addLink
- **Signature**: `addLink(string $name, Link|Reference $link): Reference`
- **Description**: Registers a link and returns a reference.

#### addCallback
- **Signature**: `addCallback(string $name, Callback|Reference $callback): Reference`
- **Description**: Registers a callback and returns a reference.

#### addPathItem
- **Signature**: `addPathItem(string $name, Path|Reference $pathItem): Reference`
- **Description**: Registers a path item and returns a reference.

#### setMediaTypes
- **Signature**: `setMediaTypes(array $mediaTypes): self`
- **Description**: Sets the media types (OAS 3.2+).

#### addMediaType
- **Signature**: `addMediaType(string $name, MediaType|Reference $mediaType): Reference`
- **Description**: Registers a media type and returns a reference.

#### removeMediaType
- **Signature**: `removeMediaType(string $name): void`
- **Description**: Removes a media type entry.

#### uniqueSchemaName
- **Signature**: `uniqueSchemaName(string $fullName)`
- **Description**: Produces a unique, slugified component name.

#### getSchemaReference
- **Signature**: `getSchemaReference(string $schemaName)`
- **Description**: Lookup for a schema reference.

#### getSchema
- **Signature**: `getSchema(string $schemaName)`
- **Description**: Lookup for a schema.

#### has
- **Signature**: `has(Reference $reference): bool`
- **Description**: Checks registry membership.

#### add
- **Signature**: `add(Reference $reference, $object): Reference`
- **Description**: Stores an object under the reference's name.

#### get
- **Signature**: `get(Reference $reference)`
- **Description**: Resolves a local reference's target.

### Usage Example
```php
use Dedoc\Scramble\Support\Generator\Components;
use Dedoc\Scramble\Support\Generator\Schema;
use Dedoc\Scramble\Support\Generator\Types\StringType;

$components = new Components;
$components->addSchema('Error', Schema::fromType((new StringType)->format('string')));
```
```

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

### Analyze a class with Scramble::infer()

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Uses Scramble::infer()->analyzeClass() to get the ClassDefinition for a model. The result is a ClassDefinition object, and the example prints its name.

```php
use Dedoc\Scramble\Scramble;

$definition = Scramble::infer()->analyzeClass(App\Models\Invoice::class);
echo $definition->name; // ClassDefinition
```

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

### Server with ServerVariable usage

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Shows how to create a Server instance with a URL template and attach a ServerVariable for the region placeholder. The variable is created with a default value, an enum of allowed values, and a description.

```php
use Dedoc\Scramble\Support\Generator\Server;
use Dedoc\Scramble\Support\Generator\ServerVariable;

(new Server('https://{region}.api.example.com'))
    ->variables(['region' => ServerVariable::make('us', ['us', 'eu'], 'Deployment region')]);
```

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

### Header attribute class definition

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Defines the Header attribute with parameters for name, description, type, format, required, default, example, examples, deprecated, explode, and status. It is repeatable on methods and functions.

```php
#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class Header
{
    /**
     * @param  scalar|array<mixed>|object|MissingValue  $example
     */
    public function __construct(
        public readonly string $name,
        public readonly ?string $description = null,
        public readonly ?string $type = null,
        public readonly ?string $format = null,
        public readonly ?bool $required = null,
        /** @var array<mixed>|scalar|null|MissingValue */
        public readonly mixed $default = new MissingValue,
        public readonly mixed $example = new MissingValue,
        /** @var array<string, Example> $examples */
        public readonly array $examples = [],
        public readonly ?bool $deprecated = null,
        public readonly ?bool $explode = null,
        public readonly int|string $status = 200,
    ) {}
}
```

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

### Analyze routes with fail-on-unknown only

Source: https://github.com/dedoc/scramble/blob/main/resources/boost/skills/scramble-development/SKILL.md

Run this command when the application has no API routes yet. Zero matched routes is expected; do not add routes or broaden matching to remove the warning.

```shell
php artisan scramble:analyze --fail-on-unknown
```

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

### Server

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Represents a server URL in the OpenAPI document. Use the constructor or make method to create a server, and chain setters to configure description, name, and variables.

```APIDOC
## Server

### Description
Represents a server URL in the OpenAPI document. Use the constructor or make method to create a server, and chain setters to configure description, name, and variables.

### Constructor
`__construct(string $url)`

### Static Factory
`make(string $url)`

### Methods
- `setDescription(string $description): Server` - Sets the server description.
- `setName(?string $name): self` - Sets the server name.
- `variables(array<string, ServerVariable> $variables)` - Sets the server variables.

### Example
```php
use Dedoc\Scramble\Support\Generator\Server;
use Dedoc\Scramble\Support\Generator\ServerVariable;

(new Server('https://{region}.api.example.com'))
    ->variables(['region' => ServerVariable::make('us', ['us', 'eu'], 'Deployment region')]);
```
```

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

### Register and use a custom API config with Scramble::registerApi

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Shows how to register a new API config named 'v2' with custom paths and info, expose UI and document routes, then retrieve the config and add an operation transformer.

```php
use Dedoc\Scramble\Scramble;

Scramble::registerApi('v2', ['api_path' => 'api/v2', 'info' => ['version' => '2.0.0']])
    ->expose(
        ui: fn ($router, $action) => $router->get('docs/v2', $action),
        document: fn ($router, $action) => $router->get('docs/v2.json', $action),
    );

// Later:
$config = Scramble::getGeneratorConfig('v2');
$config->withOperationTransformers([MyTransformer::class]);
```

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

### Customize Scramble routes with expose

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Configures the default API to expose UI at 'api-docs' and JSON document at 'api-docs.json'.

```php
use Dedoc\Scramble\Scramble;

Scramble::configure('default')->expose(
    ui: 'api-docs',
    document: 'api-docs.json',
);
```

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

### UniqueNamesOptionsCollection

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Collection of UniqueNameOptions. Provides methods to push and get unique names.

```APIDOC
## UniqueNamesOptionsCollection

### Description
Collection of UniqueNameOptions. Provides methods to push and get unique names.

### Methods
- `push(UniqueNameOptions $name)`
- `getUniqueName(UniqueNameOptions $name, ?callable $onNotUniqueFallback = null): string`
```

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

### Dedoc\Scramble\GeneratorResult

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator.md

Documentation for the GeneratorResult class, including its constructor, methods, and usage example.

```APIDOC
## GeneratorResult

### Description
Immutable result of a successful generation. Provides access to the generated OpenApi document, diagnostics, and pro-nudge collector.

### Constructor

```php
public function __construct(
    public OpenApi $openApi,
    /** @var Collection<int, Diagnostic> */
    public Collection $diagnostics,
    public ProNudgeCollector $proNudge,
)
```

### Methods

#### spec(OpenApiVersion $version = OpenApiVersion::V3_1): array

Serializes the document: `serializeAs31()` for `V3_1`, `serializeAs32()` for `V3_2`.

#### openApi(): OpenApi

Returns the `OpenApi` object.

#### diagnostics(): Collection<int, Diagnostic>

Issues collected during generation.

#### proNudge(): ProNudgeCollector

Pro-nudge collector (product suggestions).

### Example

```php
$result = $generator->generate($config);

foreach ($result->diagnostics() as $diagnostic) {
    if ($diagnostic->severity() === \Dedoc\Scramble\Diagnostics\DiagnosticSeverity::Error) {
        echo $diagnostic->code().': '.$diagnostic->message().PHP_EOL;
    }
}

file_put_contents('openapi.json', json_encode($result->spec(), JSON_PRETTY_PRINT));
```
```

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

### generate method

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator.md

Runs the full documentation pipeline: resolves routes, applies the security strategy, builds operations, enforces schemas, transforms documents, and serializes. Returns a GeneratorResult.

```php
public function generate(GeneratorConfig $config): GeneratorResult
```

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

### Analyze routes with fail-on-empty and fail-on-unknown

Source: https://github.com/dedoc/scramble/blob/main/resources/boost/skills/scramble-development/SKILL.md

Use this command to verify route selection when the application already has API routes. It fails if no routes match or if unknown routes are encountered.

```shell
php artisan scramble:analyze --fail-on-empty --fail-on-unknown
```

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

### UniqueNameOptions

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Options for generating unique names. Provides methods to get fallback names.

```APIDOC
## UniqueNameOptions

### Description
Options for generating unique names. Provides methods to get fallback names.

### Constructor
`public function __construct(public readonly ?string $eloquent, public readonly array $unique, public readonly string $separator = '.', public readonly int $fallbackEloquentPartsCount = 2)`

### Methods
- `getFallbackEloquent(): string`
- `getFallback(): string`
```

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

### preferPatchMethod(): static

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Forces documentation of PUT|PATCH routes as PATCH. Implements via resolveOperationMethodsUsing().

```APIDOC
## preferPatchMethod(): static

### Description
Forces documentation of `PUT|PATCH` routes as `PATCH`. Implements via `resolveOperationMethodsUsing()`.

### Method
preferPatchMethod

### Signature
php
public function preferPatchMethod(): static


### Return Value
- **static** - The configuration instance for chaining.
```

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

### apiPath(): ApiPath

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Returns the parsed ApiPath (cached), built with ApiPath::from($this->get('api_path'), 'api').

```APIDOC
## apiPath(): ApiPath

### Description
Returns the parsed `ApiPath` (cached), built with `ApiPath::from($this->get('api_path'), 'api')`.

### Method
apiPath

### Returns
`ApiPath` - The parsed API path.
```

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

### scramble:analyze command usage

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/console-commands.md

Runs the documentation analyzer. Supports options to select the API, filter routes, and fail on unknown types or empty docs. Issues are collected instead of aborting because exceptions are disabled.

```bash
php artisan scramble:analyze
    {--api=default : The API to analyze}
    {--routes= : Comma-separated route names to analyze}
    {--fail-on-unknown : Fail when an UnknownType schema is generated}
    {--fail-on-empty : Fail when the generated documentation contains no paths}
```

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

### MediaType

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Represents a media type object in OpenAPI. Provides setters for schema, examples, encoding, and related properties.

```APIDOC
## MediaType

### Description
Represents a media type object in OpenAPI. Provides setters for schema, examples, encoding, and related properties.

### Constructor
`public function __construct(/* see source */)`

### Methods
- `setSchema(Schema|Reference|null $schema)`
- `setItemSchema(Schema|Reference|null $itemSchema)` (OAS 3.2)
- `setExample(mixed $example)`
- `setExamples(array $examples)`
- `setEncoding(array $encoding)`
- `setPrefixEncoding(array $prefixEncoding)` (OAS 3.2)
- `setItemEncoding(?Encoding $itemEncoding)` (OAS 3.2)
- `addExample(string $key, Example|Reference $example)`
- `addEncoding(string $key, Encoding $encoding)`
- `addPrefixEncoding(Encoding $encoding)`
- `removeExample/removeEncoding/removePrefixEncoding`
```

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

### InfoObject constructor and make method

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Defines the InfoObject class constructor and static make method. The constructor accepts a title and an optional version defaulting to '0.0.1'.

```php
public function __construct(string $title, string $version = '0.0.1')
public static function make(string $title)
```

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

### Server class definition

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Defines the Server class with a constructor taking a URL, a static make method, and setters for description, name, and variables. The variables method expects an array of ServerVariable objects.

```php
class Server implements JsonSerializable, OpenApiSerializable
{
    public function __construct(string $url) {}
    public static function make(string $url)
    public function setDescription(string $description): Server
    public function setName(?string $name): self
    /** @param array<string, ServerVariable> $variables */
    public function variables(array $variables)
}
```

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

### QueryParameter usage example

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Use the QueryParameter attribute on a controller method to document a query parameter named 'status' with type 'string' and a description.

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

class InvoiceController
{
    #[QueryParameter(name: 'status', type: 'string', description: 'Filter by status')]
    public function index() {}
}
```

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

### registerJsonSpecificationRoute method signature

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Signature of the registerJsonSpecificationRoute method. Registers a GET route returning the OpenAPI JSON document (response()->json(...), pretty-printed).

```php
public static function registerJsonSpecificationRoute(string $path, string $api = 'default'): Route
```

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

### Publish Scramble configuration

Source: https://github.com/dedoc/scramble/blob/main/resources/boost/skills/scramble-development/SKILL.md

Run this artisan command to publish the Scramble configuration file when defaults need to be changed.

```shell
php artisan vendor:publish --tag=scramble-config
```

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

### Configure default API with Scramble::configure

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Returns the GeneratorConfig for the default API, allowing chained configuration calls. Throws LogicException for unregistered names.

```php
use Dedoc\Scramble\Scramble;

Scramble::configure()
    ->withOperationTransformers([MyOperationTransformer::class, Closure::fromCallable(...)]);
```

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

### SecurityScheme

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-support-objects.md

Documentation for the SecurityScheme class, including static factories and fluent setters.

```APIDOC
## SecurityScheme

### Description
Creates a security scheme object for use in OpenAPI documentation. Supports multiple types: API key, HTTP, OAuth2, OpenID Connect, and mutual TLS.

### Static Factories

#### `apiKey(string $in, string $name)`
- **Returns**: `SecurityScheme`
- **Description**: Creates an API key security scheme. `$in` can be `query`, `header`, or `cookie`. Scheme name is `apiKey`.

#### `http(string $scheme, string $bearerFormat = '')`
- **Returns**: `SecurityScheme`
- **Description**: Creates an HTTP security scheme (e.g., `scheme: 'bearer'`). Scheme name is `http`.

#### `oauth2()`
- **Returns**: `SecurityScheme`
- **Description**: Creates an OAuth2 security scheme with `OAuthFlows`. Scheme name is `oauth2`.

#### `openIdConnect(string $openIdConnectUrl)`
- **Returns**: `SecurityScheme`
- **Description**: Creates an OpenID Connect security scheme. Scheme name is `openIdConnect`.

#### `mutualTLS()`
- **Returns**: `SecurityScheme`
- **Description**: Creates a mutual TLS security scheme. Scheme name is `mutualTLS`.

### Fluent Setters

- `as(string $schemeName): self` - Sets the scheme name.
- `setDescription(string $description): self` - Sets the description.
- `setDeprecated(?bool $deprecated): self` - Sets the deprecated flag (OAS 3.2.0+).
- `setOauth2MetadataUrl(?string $oauth2MetadataUrl): self` - Sets the OAuth2 metadata URL (OAS 3.2.0+).
- `default(): self` - Marks the scheme as default.

### Example

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

Scramble::afterOpenApiGenerated(function ($openApi) {
    $openApi->secure(SecurityScheme::http('bearer'));
});
```
```

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

### Response attribute class definition

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Defines the Response attribute with parameters for status, description, mediaType, type, format, and examples. It is repeatable and targets methods and functions.

```php
/**
 * @phpstan-type BaseExample array<mixed>|scalar|null
 */
#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class Response
{
    public function __construct(
        public readonly int|string $status = 200,
        public readonly ?string $description = null,
        public readonly string $mediaType = 'application/json',
        public readonly ?string $type = null,
        public readonly ?string $format = null,
        /** @var BaseExample|BaseExample[] $examples */
        public readonly mixed $examples = [],
    ) {}
}
```

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

### Infer constructor signature

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Shows the constructor of the Infer class, which takes an Index and InferConfig. This is the public entry point for the analyzer.

```php
public function __construct(
    public Index $index,
    public InferConfig $config,
)
```

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

### Parameter class definition

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/openapi-objects.md

Defines the `Parameter` class implementing `JsonSerializable` and `OpenApiSerializable`. The constructor automatically sets `required = true` when `in === 'path'` and initializes `$example` to `new MissingValue`.

```php
class Parameter implements JsonSerializable, OpenApiSerializable
{
    use WithAttributes;
    use WithExtensions;

    public string $name;
    /** @var "query"|"header"|"path"|"cookie". */ public string $in;
    public bool $required = false;
    public ?bool $explode = null;
    /** @var "simple"|"label"|"matrix"|"form"|"spaceDelimited"|"pipeDelimited"|"deepObject"|null */ public ?string $style = null;
    public string $description = '';
    /** @var array|scalar|null|MissingValue */ public $example;
    /** @var array<string, Example> */ public array $examples = [];
    public bool $deprecated = false;
    public bool $allowEmptyValue = false;
    public bool $allowReserved = false;
    public Schema|Reference|null $schema = null;
    /** @var array<string, MediaType|Reference> */ public array $content = [];

    public function __construct(string $name, string $in) {}
}
```

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

### Export full API document to api.json

Source: https://github.com/dedoc/scramble/blob/main/resources/boost/skills/scramble-development/SKILL.md

Use this command to save the complete API document to the intended artifact path or a temporary path for inspection. Add --api=NAME for a non-default API.

```shell
php artisan scramble:export --path=api.json --fail-on-unknown
```

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

### Custom parameter extractor implementation

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/contracts-and-extensions.md

Example implementation of a custom parameter extractor. This class implements the ParameterExtractor interface and can be used to add custom parameters, such as a header, to the extraction results.

```php
use Dedoc\Scramble\Support\OperationExtensions\ParameterExtractor\ParameterExtractor;
use Dedoc\Scramble\Support\RouteInfo;
use Dedoc\Scramble\Support\OperationExtensions\RulesExtractor\ParametersExtractionResult;

class TenantParameterExtractor implements ParameterExtractor
{
    public function handle(RouteInfo $routeInfo, array $parameterExtractionResults): array
    {
        // append an InferredParameter for 'X-Tenant' header ...
        return $parameterExtractionResults;
    }
}
```

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

### expose(Closure|string|false $ui = false, Closure|string|false $document = false): static

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Controls whether documentation routes are registered for this API. Calling expose(false) clears both routes. Returns $this.

```APIDOC
## expose(Closure|string|false $ui = false, Closure|string|false $document = false): static

### Description
Controls whether documentation routes are registered for this API. Calling `expose(false)` clears both routes. `false` for either argument leaves that route unset; otherwise the given string/closure is used as route path/factory. Returns `$this`.

### Method
expose

### Parameters
- **$ui** (Closure|string|false) - Optional - Route factory/string for the UI route, or `false` to leave unset.
- **$document** (Closure|string|false) - Optional - Route factory/string for the JSON specification route, or `false` to leave unset.

### Returns
`static` - `$this` for chaining.
```

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

### Generator::__construct

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator.md

Initializes a new Generator instance with the required operation builder and route provider dependencies.

```APIDOC
## Constructor

### Signature
```php
public function __construct(
    private OperationBuilder $operationBuilder,
    private RouteProvider $routeProvider,
)
```

### Parameters
- `$operationBuilder` (OperationBuilder) - Required - Builds `Operation` objects from routes.
- `$routeProvider` (RouteProvider) - Required - Resolves the routes to document (`RouteProviderContract`).
```

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

### LogicException — unregistered API

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/errors.md

Exception raised when an API name is referenced but not registered via Scramble::registerApi.

```APIDOC
## LogicException — Unregistered API

### Description
Raised by `GeneratorConfigCollection::get('name')` and by `RouteProvider` when an `#[Api('name')]` attribute references an API that was never registered.

### Trigger Condition
- An `#[Api('name')]` attribute references an API that is not registered.

### Message
`"{name} API is not registered. Register the API using `Scramble::registerApi` first."`

### Catching Example
```php
try {
    // code that triggers the exception
} catch (\LogicException $e) {
    echo $e->getMessage();
}
```
```

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

### openApiVersion(): OpenApiVersion

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Returns the configured OpenAPI version, defaulting to V3.1.

```APIDOC
## openApiVersion(): OpenApiVersion

### Description
Returns the configured OpenAPI version, defaulting to `OpenApiVersion::V3_1`.

### Method
openApiVersion

### Signature
php
public function openApiVersion(): OpenApiVersion


### Return Value
- **OpenApiVersion** - The configured OpenAPI version.
```

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

### Dedoc\Scramble\Infer::configure

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Returns the container-bound InferConfig for mutation.

```APIDOC
## [METHOD] [ENDPOINT]

### Description
Returns the container-bound InferConfig for mutation.

### Method
[Not applicable - this is a PHP method, not an HTTP endpoint]

### Endpoint
[Not applicable - this is a PHP method, not an HTTP endpoint]

### Parameters
None

### Request Example
```php
$config = Scramble::infer()->configure();
```

### Response
#### Success Response (200)
- **InferConfig** - The container-bound InferConfig instance.

#### Response Example
```php
$config->buildDefinitionsUsingAstFor(['App\\Domain\\']);
```
```

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

### IndexBuildingBroker constructor

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Constructor for the `IndexBuildingBroker` class. The parameters are injected by the container, as indicated by the comment.

```php
public function __construct(...) // container-injected
```

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

### ExtensionsBroker constructor

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/infer.md

Constructor for the `ExtensionsBroker` class. It accepts an array of extensions, defaulting to an empty array.

```php
public function __construct(public array $extensions = [])
```

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

### Type abstract base class — src/Support/Generator/Types/Type.php

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-types.md

Abstract base class for all schema types. Implements JsonSerializable and OpenApiSerializable, uses WithAttributes and WithExtensions, and declares the type, format, description, example/default/examples, enum, const, nullable, deprecated, pattern, discriminator, xml, and externalDocs properties. The constructor accepts the type string and initializes example, default, and const to MissingValue.

```php
abstract class Type implements JsonSerializable, OpenApiSerializable
{
    use WithAttributes;
    use WithExtensions;

    public string $type;
    public string $format = '';
    public string $description = '';
    public string $contentMediaType = '';
    public string $contentEncoding = '';
    /** @deprecated @var array|scalar|null|MissingValue */ public $example;
    /** @var array|scalar|null|MissingValue */ public $default;
    /** @var array<array|scalar|null|MissingValue> */ public $examples = [];
    public array $enum = [];
    /** @var scalar|null|MissingValue */ public $const;
    public bool $nullable = false;
    public bool $deprecated = false;
    public ?string $pattern = null;
    public ?Discriminator $discriminator = null;
    public ?Xml $xml = null;
    public ?ExternalDocumentation $externalDocs = null;

    public function __construct(string $type) {}
}
```

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

### cloneWithoutExposing(?string $name = null): self

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/generator-config.md

Deep-clones the config with a new name; the clone has no exposed routes. Used as the base for registerApi().

```APIDOC
## cloneWithoutExposing(?string $name = null): self

### Description
Deep-clones the config (cloning all registered collections and the `JsonApiConfig`) with a new name; the clone has no exposed routes. Used as the base for `registerApi()`.

### Method
cloneWithoutExposing

### Parameters
- **$name** (?string) - Optional - The new name for the cloned config.

### Returns
`self` - The cloned config.
```

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

### Register UI route with Scramble::registerUiRoute

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/endpoints.md

Registers the UI route for a given API. It generates the OpenAPI specification using the CacheableGenerator and returns the configured renderer view with the spec, config, and result. The route is protected by the middleware from the 'scramble.middleware' config, defaulting to RestrictedDocsAccess.

```php
RouteFacade::get($path, function (CacheableGenerator $generator) use ($api) {
    $config = static::getGeneratorConfig($api);
    $result = $generator->generate($config);

    return view($config->renderer()->view, [
        'spec' => $result->spec($config->openApiVersion()),
        'config' => $config,
        'result' => $result,
    ]);
})->middleware($config->get('middleware', [RestrictedDocsAccess::class]));
```

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

### ServerFactory constructor signature

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/support-helpers.md

Constructor for the ServerFactory class, accepting an array of ServerVariable objects keyed by variable name.

```php
/**
 * @param  array<string, ServerVariable>  $variables
 */
public function __construct(array $variables = []) {}
```

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

### getConfigurationsInstance(): GeneratorConfigCollection — @internal

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/facade-scramble.md

Resolves the GeneratorConfigCollection singleton from the container. This method is marked as @internal.

```APIDOC
## getConfigurationsInstance(): GeneratorConfigCollection — @internal

### Description
Resolves the GeneratorConfigCollection singleton from the container. This method is marked as @internal.

### Method
N/A (PHP static method)

### Endpoint
N/A

### Parameters
None.

### Response
#### Success Response
- **GeneratorConfigCollection** - The configuration collection instance.

```

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

### Import attributes

Source: https://github.com/dedoc/scramble/blob/main/_autodocs/api-reference/attributes.md

Import the QueryParameter and Response attributes from the Dedoc\Scramble\Attributes namespace.

```php
use Dedoc\Scramble\Attributes\QueryParameter;
use Dedoc\Scramble\Attributes\Response;
```
Tokens:
Raw