L5 Swagger

https://github.com/darkaonline/l5-swagger
Admin
L5 Swagger provides OpenApi or Swagger Specification for Laravel projects, making it easy to...
Tokens:48,112
Snippets:330
Trust Score:9
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Multiple Response Examples with OA\Examples

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint with a path parameter that accepts either an integer or UUID, providing examples for each. The 200 response includes a user object example. Use when you need to document multiple possible values for a parameter or response.

```php
#[OA\Get(
    path: "/api/users/{id}",
    summary: "Get user by ID",
    tags: ["Users"],
    parameters: [
        new OA\Parameter(
            name: "id",
            in: "path",
            required: true,
            examples: [
                new OA\Examples(
                    example: "int",
                    summary: "Integer ID",
                    value: 1
                ),
                new OA\Examples(
                    example: "uuid",
                    summary: "UUID",
                    value: "0006faf6-7a61-426c-9034-579f2cfcfa83"
                )
            ],
            schema: new OA\Schema(
                oneOf: [
                    new OA\Schema(type: "integer"),
                    new OA\Schema(type: "string", format: "uuid")
                ]
            )
        )
    ],
    responses: [
        new OA\Response(
            response: 200,
            description: "Success",
            content: new OA\JsonContent(
                examples: [
                    new OA\Examples(
                        example: "user",
                        summary: "User object",
                        value: [
                            "id" => 1,
                            "name" => "John Doe",
                            "email" => "john@example.com"
                        ]
                    )
                ]
            )
        ),
        new OA\Response(response: 404, description: "User not found")
    ]
)]
public function show($id)
{
    // Your code
}
```

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

### GET /api/users/{id} - Multiple Response Examples

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint with multiple examples for the path parameter and response content.

```APIDOC
## GET /api/users/{id}

### Description
Retrieves a user by ID. Supports both integer and UUID identifiers.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (integer or string) - Required - User ID, can be an integer or a UUID string.

### Response
#### Success Response (200)
- **id** (integer) - User ID
- **name** (string) - User name
- **email** (string) - User email

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

#### Error Response (404)
- **description** (string) - User not found
```

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

### Example: YAML-oriented custom asset path (config override)

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/helpers.md

Shows a config/l5-swagger.php override for swagger_ui_assets_path and use_absolute_path.

```php
// config/l5-swagger.php
'documentations' => [
    'default' => [
        'paths' => [
            'swagger_ui_assets_path' => env('L5_SWAGGER_UI_ASSETS_PATH', 'vendor/swagger-api/swagger-ui/dist/'),
            'use_absolute_path' => true,
        ],
    ],
],
```

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

### Direct controller invocation example

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/swagger-asset-controller.md

Shows how to invoke the controller directly with a Request, set the documentation and asset offsets, and inspect the response headers.

```php
use Illuminate\Http\Request;
use L5Swagger\Http\Controllers\SwaggerAssetController;

$request = Request::create('/docs/asset/swagger-ui.css', 'GET');
$request->offsetSet('documentation', 'default');
$request->offsetSet('asset', 'swagger-ui.css');

/** @var \Illuminate\Http\Response $response */
$response = app(SwaggerAssetController::class)->index($request);

$contentType = $response->headers->get('Content-Type'); // text/css
$cacheSeconds = $response->headers->getCacheControlDirective('max-age'); // 31536000
```

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

### Example: resolve the dist directory

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/helpers.md

Calls swagger_ui_dist_path('default') to get the absolute path to the swagger-ui dist directory. The comment shows an example output.

```php
$distDir = swagger_ui_dist_path('default');
// /var/www/app/vendor/swagger-api/swagger-ui/dist
```

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

### Example: generate a versioned asset URL

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/helpers.md

Calls l5_swagger_asset('default', 'swagger-ui-bundle.js') to get a URL with a cache-busting md5 query parameter. The comment shows the URL format.

```php
$jsUrl = l5_swagger_asset('default', 'swagger-ui-bundle.js');
// https://example.com/api/documentation/asset/swagger-ui-bundle.js?v=<md5>
```

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

### Using the container binding to generate docs

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/service-provider.md

Example of resolving the Generator from the container and calling generateDocs(). This uses the default documentation set as configured.

```php
$generator = app(L5Swagger\Generator::class);
$generator->generateDocs();
```

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

### Applying the middleware manually to custom routes

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/config-middleware.md

Example of applying the Config middleware to a custom route and setting the documentation action parameter.

```php
use Illuminate\Support\Facades\Route;
use L5Swagger\Http\Middleware\Config as L5SwaggerConfig;

Route::get('/custom-swagger-info', function () {
    $config = request()->offsetGet('config');

    return view('info', ['title' => $config['api']['title'] ?? 'API']);
})->middleware(L5SwaggerConfig::class)->setDefaults(['l5-swagger.documentation' => 'default']);
```

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

### Before v9.x: DocBlock Get Annotation

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the old DocBlock annotation for a GET endpoint, used before migrating to PHP 8 attributes.

```php
<?php

namespace App\Http\Controllers;

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="Get users list",
 *     tags={"Users"},
 *     @OA\Response(
 *         response=200,
 *         description="Successful operation",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/User")
 *         )
 *     )
 * )
 */
public function index()
{
    //
}
```

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

### Generated OAuth2 callback URL example

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/swagger-controller.md

Example of generating the OAuth2 callback URL using the route() helper. The output is shown as a comment.

```php
$redirectUrl = route('l5-swagger.default.oauth2_callback', [], true);
// https://example.com/api/oauth2-callback
```

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

### Browser request example with cache busting

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/swagger-asset-controller.md

HTML link tag showing how a browser requests the asset with a cache-busting query string.

```html
<link rel="stylesheet" type="text/css" href="/api/documentation/asset/swagger-ui.css?v=0d8672887b8d2a6e4b0b26bcdd2eb4a5">
```

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

### After v10.0: PHP 8 Get Attribute

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the new PHP 8 attribute syntax for a GET endpoint, replacing the DocBlock annotation.

```php
<?php

namespace App\Http\Controllers;

use OpenApi\Attributes as OA;

#[OA\Get(
    path: "/api/users",
    summary: "Get users list",
    tags: ["Users"],
    responses: [
        new OA\Response(
            response: 200,
            description: "Successful operation",
            content: new OA\JsonContent(
                type: "array",
                items: new OA\Items(ref: "#/components/schemas/User")
            )
        )
    ]
)]
public function index()
{
    //
}
```

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

### Get merged config for default documentation

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/config-factory.md

Retrieves the merged configuration for the default documentation set using the documentationConfig() method. The example shows how to access the docs path and check the format.

```php
use L5Swagger\ConfigFactory;

/** @var ConfigFactory $factory */
$factory = app(ConfigFactory::class);

$config = $factory->documentationConfig();       // uses l5-swagger.default

$docsPath = $config['paths']['docs'];            // e.g. storage_path('api-docs')
$isYaml    = ($config['paths']['format_to_use_for_docs'] ?? 'json') === 'yaml';
```

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

### Facade usage to generate docs

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/service-provider.md

Example of using the L5Swagger facade to call generateDocs(). The facade forwards to the bound Generator instance.

```php
use L5Swagger;

L5Swagger::generateDocs();
```

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

### Standalone usage of SecurityDefinitions

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/security-definitions.md

Example showing how to instantiate SecurityDefinitions with a sanctum API key scheme and a global security requirement, then call generate() on a JSON file. The file must already exist.

```php
use L5Swagger\SecurityDefinitions;

$security = new SecurityDefinitions(
    schemasConfig: [
        'sanctum' => [
            'type' => 'apiKey',
            'description' => 'Enter token in format (Bearer <token>)',
            'name' => 'Authorization',
            'in' => 'header',
        ],
    ],
    securityConfig: [
        ['sanctum' => []],
    ]
);

$security->generate(storage_path('api-docs/api-docs.json'));
```

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

### Using request offsets in a controller

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/config-middleware.md

Example controller method that retrieves the documentation name and merged config from request offsets set by the middleware.

```php
public function show(Request $request)
{
    $documentation = $request->offsetGet('documentation'); // e.g. 'default'
    $config = $request->offsetGet('config');               // merged array

    return response()->json([
        'docs' => $config['paths']['docs'],
        'title' => $config['api']['title'] ?? $documentation,
    ]);
}
```

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

### GET /api/users - List users with OA\Get

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint that returns a paginated list of users. Includes a 200 response with an array of User schema items and a 401 Unauthenticated response.

```php
#[OA\Get(
    path: "/api/users",
    summary: "Get list of users",
    description: "Returns a paginated list of all users",
    tags: ["Users"],
    responses: [
        new OA\Response(
            response: 200,
            description: "Successful operation",
            content: new OA\JsonContent(
                type: "array",
                items: new OA\Items(ref: "#/components/schemas/User")
            )
        ),
        new OA\Response(
            response: 401,
            description: "Unauthenticated"
        )
    ]
)]
public function index()
{
    // Your code
}
```

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

### After v10.0: Security Scheme Attribute

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the new PHP 8 attribute syntax for a security scheme, replacing the DocBlock annotation.

```php
use OpenApi\Attributes as OA;

#[OA\SecurityScheme(
    securityScheme: "bearerAuth",
    type: "http",
    scheme: "bearer",
    bearerFormat: "JWT"
)]
```

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

### Before v9.x: Security Scheme Annotation

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the old DocBlock annotation for a security scheme, used before migrating to PHP 8 attributes.

```php
/**
 * @OA\SecurityScheme(
 *     securityScheme="bearerAuth",
 *     type="http",
 *     scheme="bearer",
 *     bearerFormat="JWT"
 * )
 */
```

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

### Before v9.x: DocBlock Info Annotation

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the old DocBlock annotation for OpenAPI info, used before migrating to PHP 8 attributes.

```php
<?php

namespace App\Http\Controllers;

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="My API",
 *     description="API description",
 *     @OA\Contact(
 *         email="contact@example.com"
 *     ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="https://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */
class Controller
{
}
```

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

### GET {routes.docs}

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/endpoints.md

Serves the generated OpenAPI documentation file in JSON or YAML format. The format is determined by the 'paths.format_to_use_for_docs' configuration. When 'generate_always' is enabled, the documentation is regenerated on each request.

```APIDOC
## GET {routes.docs}

### Description
Serves the generated OpenAPI documentation file in JSON or YAML format. The format is determined by the `paths.format_to_use_for_docs` configuration. When `generate_always` is enabled, the documentation is regenerated on each request.

### Method
GET

### Endpoint
`{routes.docs}` (default: `/docs`)

### Parameters
No parameters.

### Response
#### Success Response (200)
- **Content-Type**: `application/json` (if format is `json`) or `application/yaml` (if format is `yaml`)
- **Body**: The generated OpenAPI document. For JSON, the body is the content of `{paths.docs}/{paths.docs_json}` (default `storage_path('api-docs/api-docs.json')`). For YAML, the body is the content of `{paths.docs}/{paths.docs_yaml}` (default `api-docs.yaml`). Note: the YAML file only exists if `generate_yaml_copy` is enabled.
- **Content-Disposition**: `inline` (for YAML format)

#### Response Example
(No example provided in source)

#### Error Responses
- **404**: Documentation file not found or regeneration failed. Conditions: `generate_always` regeneration failed (`Unable to generate documentation file to: "{path}"...`) or file not found (`Unable to locate documentation file at: "{path}"`).

### Side Effects
When `generate_always` is truthy, the docs are regenerated on each request. A warning is logged when the app environment is `production`.
```

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

### Example: resolve a specific asset with error handling

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/helpers.md

Calls swagger_ui_dist_path('default', 'swagger-ui.css') inside a try-catch to handle L5SwaggerException. The comment shows the error message for unknown assets.

```php
use L5Swagger\Exceptions\L5SwaggerException;

try {
    $css = swagger_ui_dist_path('default', 'swagger-ui.css');
} catch (L5SwaggerException $e) {
    // "(bootstrap.css) - this L5 Swagger asset is not allowed" for unknown assets
    abort(404, $e->getMessage());
}
```

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

### Manual application registration in config/app.php

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/service-provider.md

Example of manually registering the L5SwaggerServiceProvider in the Laravel application's provider list. This is optional because the provider is auto-discovered via composer.

```php
// config/app.php
'providers' => [
    // ...
    L5Swagger\L5SwaggerServiceProvider::class,
],
```

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

### GET {routes.api}

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/endpoints.md

Serves the Swagger UI HTML page for a documentation set. Publicly accessible by default; configure routes.middleware.api to add authentication in production.

```APIDOC
## GET {routes.api}

### Description
Serves the Swagger UI HTML page for a documentation set. The page renders the Swagger UI bundle and initializes it with all documentation sets.

### Method
GET

### Endpoint
{routes.api} (default: /api/documentation)

### Parameters
No query parameters required.

### Response
#### Success Response (200)
- HTML page rendering the Swagger UI bundle.

#### Response Example
(HTML content)

### Notes
- Route name: l5-swagger.{documentation}.api
- Handler: SwaggerController@api
- Middleware: routes.middleware.api (default []) + Config middleware
- Auth: None by default; configure routes.middleware.api
- Side effects: If config['proxy'] is set, trusted proxies are applied. If additional_config_url has an invalid scheme, it is logged and ignored.
```

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

### GET {routes.docs}/asset/{asset}

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/endpoints.md

Serves static assets used by the Swagger UI. The asset must be in the allowlist. Responses are cached for one year.

```APIDOC
## GET {routes.docs}/asset/{asset}

### Description
Serves static assets used by the Swagger UI. The asset must be in the allowlist. Responses are cached for one year.

### Method
GET

### Endpoint
`{routes.docs}/asset/{asset}` (default: `/docs/asset/{asset}`)

### Parameters
#### Path Parameters
- **asset** (string) - Required - One of the allowlisted files: `favicon-16x16.png`, `favicon-32x32.png`, `oauth2-redirect.html`, `swagger-ui-bundle.js`, `swagger-ui-standalone-preset.js`, `swagger-ui.css`, `swagger-ui.js`.

### Response
#### Success Response (200)
- **Content-Type**: `image/png` (for `.png`), `application/javascript` (for `.js`), `text/css` (default)
- **Cache-Control**: `max-age=31536000, public` (via `setSharedMaxAge`+`setMaxAge`)
- **Expires**: `+1 year`

#### Response Example
(No example provided in source)

#### Error Responses
- **404**: Asset not allowlisted, file missing, or directory missing. Conditions: `(name) - this L5 Swagger asset is not allowed`, `Swagger UI asset not found at: "..."`, `Swagger UI assets directory not found at: "..."`.
```

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

### Define Header Parameters with OA\Parameter

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Shows how to define optional header parameters using OA\Parameter with 'in: header'. The example includes X-Api-Version and Accept-Language headers, with defaults and an enum for language.

```php
#[OA\Get(
    path: "/api/users",
    summary: "Get users",
    tags: ["Users"],
    parameters: [
        new OA\Parameter(
            name: "X-Api-Version",
            description: "API version",
            in: "header",
            required: false,
            schema: new OA\Schema(type: "string", default: "v1")
        ),
        new OA\Parameter(
            name: "Accept-Language",
            description: "Preferred language",
            in: "header",
            required: false,
            schema: new OA\Schema(type: "string", enum: ["en", "es", "fr"], default: "en")
        )
    ],
    responses: [
        new OA\Response(response: 200, description: "Success")
    ]
)]
public function index(Request $request)
{
    // Your code
}
```

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

### After v10.0: PHP 8 Info Attribute

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the new PHP 8 attribute syntax for OpenAPI info, replacing the DocBlock annotation.

```php
<?php

namespace App\Http\Controllers;

use OpenApi\Attributes as OA;

#[OA\Info(
    version: "1.0.0",
    title: "My API",
    description: "API description",
    contact: new OA\Contact(
        email: "contact@example.com"
    ),
    license: new OA\License(
        name: "Apache 2.0",
        url: "https://www.apache.org/licenses/LICENSE-2.0.html"
    )
)]
class Controller
{
}
```

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

### Basic Schema with OA\Schema Attribute

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a basic 'User' schema with required properties and examples. Use this as a template for simple data models.

```php
<?php

namespace App\Models;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: "User",
    title: "User",
    description: "User model",
    required: ["id", "name", "email"],
    properties: [
        new OA\Property(property: "id", type: "integer", example: 1),
        new OA\Property(property: "name", type: "string", example: "John Doe"),
        new OA\Property(property: "email", type: "string", format: "email", example: "john@example.com"),
        new OA\Property(property: "created_at", type: "string", format: "date-time", example: "2024-01-01T00:00:00Z"),
        new OA\Property(property: "updated_at", type: "string", format: "date-time", example: "2024-01-01T00:00:00Z")
    ]
)]
class User
{
    // Your model code
}
```

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

### Define Query Parameters with OA\Parameter

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Shows how to define optional query parameters using OA\Parameter with 'in: query'. The example includes page, per_page, status, and search parameters, with defaults and an enum for status.

```php
#[OA\Get(
    path: "/api/users",
    summary: "Get users with filtering and pagination",
    tags: ["Users"],
    parameters: [
        new OA\Parameter(
            name: "page",
            description: "Page number",
            in: "query",
            required: false,
            schema: new OA\Schema(type: "integer", default: 1)
        ),
        new OA\Parameter(
            name: "per_page",
            description: "Items per page",
            in: "query",
            required: false,
            schema: new OA\Schema(type: "integer", default: 15, maximum: 100)
        ),
        new OA\Parameter(
            name: "status",
            description: "Filter by status",
            in: "query",
            required: false,
            schema: new OA\Schema(type: "string", enum: ["active", "inactive", "pending"])
        ),
        new OA\Parameter(
            name: "search",
            description: "Search term",
            in: "query",
            required: false,
            schema: new OA\Schema(type: "string")
        )
    ],
    responses: [
        new OA\Response(response: 200, description: "Success")
    ]
)]
public function index(Request $request)
{
    // Your code
}
```

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

### Error handling for generateDocs()

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator.md

Example of catching L5SwaggerException and other throwables when calling generateDocs(). The L5SwaggerException message may be 'Documentation storage directory is not writable'.

```php
use L5Swagger\Exceptions\L5SwaggerException;

try {
    $generator->generateDocs();
} catch (L5SwaggerException $e) {
    // e.g. "Documentation storage directory is not writable"
    logger()->error('Swagger docs generation failed', ['error' => $e->getMessage()]);
} catch (\Throwable $e) {
    // scanning errors from swagger-php surface here
    report($e);
}
```

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

### Publish new views (2.0 to 3.0)

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this artisan command to publish the new views.

```bash
l5-swagger:publish-views
```

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

### Publish new config (2.0 to 3.0)

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this artisan command to publish the new configuration file.

```bash
l5-swagger:publish-config
```

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

### Publish config and views for L5-Swagger (versions >= 6)

Source: https://github.com/darkaonline/l5-swagger/wiki/Installation-&-Configuration

Publish L5-Swagger's config and view files into your project, then generate the documentation.

```bash
$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
$ php artisan l5-swagger:generate
```

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

### Publish new swagger-ui assets (2.0 to 3.0)

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this artisan command to publish the new swagger-ui assets.

```bash
l5-swagger:publish-assets
```

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

### GET /api/users/{id} - Get user by ID with OA\Get

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint with a required path parameter 'id' of type integer. Returns a single User schema on success and a 404 response if not found.

```php
#[OA\Get(
    path: "/api/users/{id}",
    summary: "Get user by ID",
    description: "Returns a single user",
    tags: ["Users"],
    parameters: [
        new OA\Parameter(
            name: "id",
            description: "User ID",
            in: "path",
            required: true,
            schema: new OA\Schema(type: "integer")
        )
    ],
    responses: [
        new OA\Response(
            response: 200,
            description: "Successful operation",
            content: new OA\JsonContent(ref: "#/components/schemas/User")
        ),
        new OA\Response(
            response: 404,
            description: "User not found"
        )
    ]
)]
public function show($id)
{
    // Your code
}
```

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

### make() method signature

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator-factory.md

Creates a new Generator instance for the given documentation set name. Throws L5SwaggerException if the documentation set does not exist.

```php
public function make(string $documentation): Generator
```

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

### GET /api/download/{fileId}

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint for downloading a file, including custom response headers.

```APIDOC
## GET /api/download/{fileId}

### Description
Defines a GET endpoint for downloading a file, including custom response headers.

### Method
GET

### Endpoint
/api/download/{fileId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The file identifier.

### Response
#### Success Response (200)
- **Content-Disposition** (string) - Attachment filename.
- **Content-Type** (string) - Media type of the file.
- Body: binary file content.

### Response Example
```
Content-Disposition: attachment; filename=document.pdf
Content-Type: application/pdf

[Binary file content]
```

### Code Example
```php
#[OA\Get(
    path: "/api/download/{fileId}",
    summary: "Download file",
    tags: ["Files"],
    parameters: [
        new OA\Parameter(name: "fileId", in: "path", required: true, schema: new OA\Schema(type: "string"))
    ],
    responses: [
        new OA\Response(
            response: 200,
            description: "File content",
            headers: [
                new OA\Header(
                    header: "Content-Disposition",
                    description: "Attachment filename",
                    schema: new OA\Schema(type: "string"),
                    example: "attachment; filename=document.pdf"
                ),
                new OA\Header(
                    header: "Content-Type",
                    schema: new OA\Schema(type: "string"),
                    example: "application/pdf"
                )
            ],
            content: new OA\MediaType(
                mediaType: "application/octet-stream",
                schema: new OA\Schema(type: "string", format: "binary")
            )
        )
    ]
)]
public function download($fileId)
{
    // Your code
}
```
```

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

### Constructor

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/security-definitions.md

Creates a new SecurityDefinitions instance with optional security scheme definitions and global security requirements.

```APIDOC
## Constructor

### Description
Creates a new SecurityDefinitions instance.

### Signature
```php
public function __construct(
    private readonly array $schemasConfig = [],
    private readonly array $securityConfig = []
)
```

### Parameters
- **$schemasConfig** (array<string,mixed>) - Optional - Security scheme definitions, from `l5-swagger.defaults.securityDefinitions.securitySchemes`. Keys become scheme names under `components.securitySchemes`.
- **$securityConfig** (array<string,mixed>) - Optional - Global security requirements, from `l5-swagger.defaults.securityDefinitions.security`.

### Example
```php
$security = new SecurityDefinitions(
    schemasConfig: [
        'sanctum' => [
            'type' => 'apiKey',
            'description' => 'Enter token in format (Bearer <token>)',
            'name' => 'Authorization',
            'in' => 'header',
        ],
    ],
    securityConfig: [
        ['sanctum' => []],
    ]
);
```
```

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

### GET /api/users/{id} - Response with Multiple Content Types

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Defines a GET endpoint that can return either JSON or XML content for the user resource.

```APIDOC
## GET /api/users/{id}

### Description
Retrieves a user by ID. The response can be in JSON or XML format.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - User ID.

### Response
#### Success Response (200)
- **content** (object) - User object, available as JSON or XML.

#### Response Example (JSON)
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

#### Response Example (XML)
<user>
  <id>1</id>
  <name>John Doe</name>
  <email>john@example.com</email>
</user>
```

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

### Build generators for several documentation sets

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator-factory.md

Iterates over all configured documentation keys and generates docs for each. This mirrors the internal behavior of the `l5-swagger:generate --all` command.

```php
use L5Swagger\GeneratorFactory;

$factory = app(GeneratorFactory::class);

foreach (array_keys(config('l5-swagger.documentations', [])) as $name) {
    $factory->make($name)->generateDocs();
}
```

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

### Blade template example for Swagger UI variables

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/swagger-controller.md

Example of view variables passed to the Blade template in resources/views/vendor/l5-swagger/index.blade.php. Uses SwaggerUIBundle with urls, operationsSorter, validatorUrl, and docExpansion.

```php
// In resources/views/vendor/l5-swagger/index.blade.php
<script>
    window.onload = function () {
        SwaggerUIBundle({
            urls: @json($urlsToDocs),
            operationsSorter: @json($operationsSorter ?? null),
            validatorUrl: @json($validatorUrl ?? null),
            docExpansion: @json(config('l5-swagger.defaults.ui.display.doc_expansion', 'none')),
        });
    };
</script>
```

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

### Catch L5SwaggerException in swagger_ui_dist_path

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/errors.md

Example of catching L5SwaggerException when using swagger_ui_dist_path.

```APIDOC
## Catch L5SwaggerException in swagger_ui_dist_path

### Description
Example of catching L5SwaggerException when using swagger_ui_dist_path.

### Code
```php
use L5Swagger\Exceptions\L5SwaggerException;

try {
    $path = swagger_ui_dist_path('default', 'swagger-ui.js');
} catch (L5SwaggerException $e) {
    // "(.php) - this L5 Swagger asset is not allowed" (not in allowlist)
    // "Swagger UI asset not found at: ..."
    abort(404, $e->getMessage());
}
```
```

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

### Regenerate Documentation for Multiple Sets

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this command to regenerate documentation for all documentation sets.

```bash
php artisan l5-swagger:generate --all
```

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

### Catch L5SwaggerException in GeneratorFactory

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/errors.md

Example of catching L5SwaggerException when generating documentation.

```APIDOC
## Catch L5SwaggerException in GeneratorFactory

### Description
Example of catching L5SwaggerException when generating documentation.

### Code
```php
use L5Swagger\Exceptions\L5SwaggerException;
use L5Swagger\GeneratorFactory;

try {
    app(GeneratorFactory::class)->make('default')->generateDocs();
} catch (L5SwaggerException $e) {
    // Directory problems & missing config
    // messages: "Documentation storage directory is not writable",
    //           "Documentation storage directory could not be created",
    //           "Documentation config not found"
    report($e);
} catch (\Throwable $e) {
    // swagger-php scanning / YAML / filesystem errors propagate as-is
    report($e);
}
```
```

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

### GET /api/users

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Returns a paginated list of all users. This endpoint is used to retrieve a collection of user resources.

```APIDOC
## [GET] /api/users

### Description
Returns a paginated list of all users.

### Method
GET

### Endpoint
/api/users

### Parameters
None

### Response
#### Success Response (200)
- **items** (array) - Array of User objects

#### Response Example
{
  "items": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ]
}

#### Error Response (401)
- **description** (string) - Unauthenticated
```

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

### Instance-form registration with container-injected dependencies

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/custom-generator-interface.md

Shows how to register a custom generator factory as a singleton and pass an instance to generator_factory, useful when the factory has dependencies.

```php
// In a service provider
$this->app->singleton(MyCustomGeneratorFactory::class);

// config/l5-swagger.php
'scanOptions' => [
    'generator_factory' => app(\App\Swagger\MyCustomGeneratorFactory::class),
],

```

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

### Run a single test file with PHPUnit

Source: https://github.com/darkaonline/l5-swagger/blob/master/CLAUDE.md

Runs all tests in the specified test file using the vendor binary.

```bash
vendor/bin/phpunit tests/Unit/GeneratorTest.php
```

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

### Publish new swagger-ui view and configuration (3.0/4.0 to 5.0)

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this artisan command to publish the new swagger-ui view and configuration after removing the old config and view files.

```bash
l5-swagger:publish
```

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

### Publish new swagger-ui view and configuration (7.0 to 8.0)

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this artisan command to publish the new swagger-ui view and configuration after removing the old config and view files.

```bash
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
```

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

### boot() method signature

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/service-provider.md

Signature of the boot method in L5SwaggerServiceProvider. It loads views, publishes config and views, loads routes, and registers the GenerateDocsCommand.

```php
public function boot(): void
```

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

### After v10.0: Complex Schema Attribute

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the new PHP 8 attribute syntax for a complex schema, replacing the DocBlock annotation.

```php
use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: "User",
    type: "object",
    required: ["id", "name", "email"],
    properties: [
        new OA\Property(
            property: "id",
            type: "integer",
            description: "User ID"
        ),
        new OA\Property(
            property: "name",
            type: "string",
            description: "User name"
        ),
        new OA\Property(
            property: "email",
            type: "string",
            format: "email",
            description: "User email"
        )
    ]
)]
class User
{
}
```

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

### Before v9.x: Complex Schema Annotation

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Example of the old DocBlock annotation for a complex schema, used before migrating to PHP 8 attributes.

```php
/**
 * @OA\Schema(
 *     schema="User",
 *     type="object",
 *     required={"id", "name", "email"},
 *     @OA\Property(
 *         property="id",
 *         type="integer",
 *         description="User ID"
 *     ),
 *     @OA\Property(
 *         property="name",
 *         type="string",
 *         description="User name"
 *     ),
 *     @OA\Property(
 *         property="email",
 *         type="string",
 *         format="email",
 *         description="User email"
 *     )
 * )
 */
class User
{
}
```

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

### Publish L5-Swagger config and views

Source: https://github.com/darkaonline/l5-swagger/wiki/Using-Swagger-UI-with-Passport

Run this artisan command to publish L5-Swagger's configuration and view files into your project. This is the first step before editing the configuration.

```bash
$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
```

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

### L5-Swagger Multi-Documentation Configuration

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/configuration.md

This configuration defines two documentation instances: 'public' and 'internal'. The 'internal' documentation has custom paths, routes, and middleware (auth:sanctum). The 'defaults' section sets global paths, scan options, security schemes, UI display, and constants. Use this as a template for setting up multiple API documentations with different access controls.

```php
<?php

return [
    'default' => 'public',
    'documentations' => [
        'public' => [
            'api' => ['title' => 'Public API'],
        ],
        'internal' => [
            'api' => ['title' => 'Internal API'],
            'paths' => [
                'annotations' => [base_path('app/Internal')],
                'docs' => storage_path('api-docs-internal'),
            ],
            'routes' => [
                'api' => 'internal/documentation',
                'docs' => 'internal/docs',
                'middleware' => [
                    'api' => ['auth:sanctum'],
                    'docs' => ['auth:sanctum'],
                    'asset' => [],
                    'oauth2_callback' => [],
                ],
            ],
        ],
    ],
    'defaults' => [
        'paths' => [
            'docs' => storage_path('api-docs'),
            'base' => env('L5_SWAGGER_BASE_PATH', '/api/v1'),
        ],
        'scanOptions' => [
            'exclude' => [base_path('app/Console')],
            'open_api_spec_version' => env('L5_SWAGGER_OPEN_API_SPEC_VERSION', '3.0.0'),
        ],
        'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),
        'securityDefinitions' => [
            'securitySchemes' => [
                'sanctum' => [
                    'type' => 'apiKey',
                    'description' => 'Enter token in format (Bearer <token>)',
                    'name' => 'Authorization',
                    'in' => 'header',
                ],
            ],
            'security' => [['sanctum' => []]],
        ],
        'ui' => [
            'display' => ['dark_mode' => env('L5_SWAGGER_UI_DARK_MODE', false)],
        ],
        'constants' => [
            'L5_SWAGGER_CONST_HOST' => env('L5_SWAGGER_CONST_HOST', 'http://my-default-host.com'),
        ],
    ],
];
```

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

### GET /api/users/{id}

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Returns a single user by ID. This endpoint retrieves a specific user resource based on the provided path parameter.

```APIDOC
## [GET] /api/users/{id}

### Description
Returns a single user.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - User ID

### Response
#### Success Response (200)
- **User** (object) - The user object

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

#### Error Response (404)
- **description** (string) - User not found
```

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

### generate(string $filename): void

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/security-definitions.md

Reads the JSON documentation at the given filename, injects security schemes and security requirements, and writes the file back.

```APIDOC
## generate(string $filename): void

### Description
Post-processes the generated JSON documentation to inject security scheme definitions and security requirements.

### Method
`generate`

### Signature
```php
public function generate(string $filename): void
```

### Parameters
- **$filename** (string) - Required - Path to the JSON documentation file.

### Behavior
1. Reads the JSON documentation at `$filename` (must already exist — this runs after `Generator::saveJson()`).
2. If `schemasConfig` is non-empty, calls `injectSecuritySchemes()` to merge `components.securitySchemes`.
3. If `securityConfig` is non-empty, calls `injectSecurity()` to merge the top-level `security` array.
4. Writes the file back using `Collection::toJson(JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)`.

### Return Type
`void`

### Throws
- **FileNotFoundException** - `Illuminate\Contracts\Filesystem\FileNotFoundException` — the JSON file at `$filename` cannot be read (also propagates any file-system error on write).

### Example
```php
use L5Swagger\SecurityDefinitions;

$security = new SecurityDefinitions(
    schemasConfig: [
        'sanctum' => [
            'type' => 'apiKey',
            'description' => 'Enter token in format (Bearer <token>)',
            'name' => 'Authorization',
            'in' => 'header',
        ],
    ],
    securityConfig: [
        ['sanctum' => []],
    ]
);

$security->generate(storage_path('api-docs/api-docs.json'));
```
```

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

### Resolve a named documentation set

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator-factory.md

Shows how to obtain a Generator for a documentation set (e.g., 'default') and generate its docs. The factory is typically resolved from the container.

```php
use L5Swagger\GeneratorFactory;

/** @var GeneratorFactory $factory */
$factory = app(GeneratorFactory::class);

$generator = $factory->make('default');   // or any other key of l5-swagger.documentations
$generator->generateDocs();
```

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

### Regenerate Documentation

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Run this command to regenerate the Swagger documentation after converting annotations.

```bash
php artisan l5-swagger:generate
```

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

### generateDocs(): void

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator.md

Runs the full documentation generation pipeline, including directory preparation, constant definition, annotation scanning, server population, JSON saving, and optional YAML copy. This is the primary method users call to generate API documentation.

```APIDOC
## generateDocs(): void

### Description
Runs the full generation pipeline as a fluent chain, writing the OpenAPI documentation to the configured docs directory. This method is the primary entry point for generating API documentation.

### Method
`generateDocs()`

### Signature
```php
public function generateDocs(): void
```

### Parameters
None (uses constructor-injected configuration)

### Return Type
`void` — writes files to `paths.docs`.

### Throws
| Error type | Condition |
|-----------|-----------|
| `L5SwaggerException` | Docs directory exists but is not writable; or the directory could not be created. |
| `Exception` | Any exception propagated from swagger-php scanning / OpenAPI generation. |
| `FileNotFoundException` | JSON file cannot be read for the YAML copy step. |

### Example — direct invocation (inside a Laravel context)
```php
use L5Swagger\Generator;
use L5Swagger\SecurityDefinitions;

$generator = new Generator(
    paths: [
        'annotations' => [base_path('app')],
        'docs' => storage_path('api-docs'),
        'docs_json' => 'api-docs.json',
        'docs_yaml' => 'api-docs.yaml',
        'excludes' => [],
        'base' => '/api',
    ],
    constants: ['L5_SWAGGER_CONST_HOST' => 'https://example.com'],
    yamlCopyRequired: true,
    security: new SecurityDefinitions([], []),
    scanOptions: ['open_api_spec_version' => Generator::OPEN_API_DEFAULT_SPEC_VERSION],
);

$generator->generateDocs();
```

### Example — error handling
```php
use L5Swagger\Exceptions\L5SwaggerException;

try {
    $generator->generateDocs();
} catch (L5SwaggerException $e) {
    // e.g. "Documentation storage directory is not writable"
    logger()->error('Swagger docs generation failed', ['error' => $e->getMessage()]);
} catch (\Throwable $e) {
    // scanning errors from swagger-php surface here
    report($e);
}
```
```

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

### Regenerate specific and all docs commands

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/console-command.md

Two separate commands: one to regenerate a specific documentation set named 'store', and one to regenerate all sets using the --all flag.

```bash
php artisan l5-swagger:generate store
```

```bash
php artisan l5-swagger:generate --all
```

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

### Apply Bearer Token security to endpoint

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Applies the 'bearerAuth' security scheme to a GET endpoint for /api/profile. Includes a 401 response for unauthenticated requests.

```php
#[OA\Get(
    path: "/api/profile",
    summary: "Get user profile",
    tags: ["Profile"],
    security: [["bearerAuth" => []]],
    responses: [
        new OA\Response(response: 200, description: "Success"),
        new OA\Response(response: 401, description: "Unauthenticated")
    ]
)]
public function profile()
{
    // Your code
}
```

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

### Direct invocation of Generator with generateDocs()

Source: https://github.com/darkaonline/l5-swagger/blob/master/_autodocs/api-reference/generator.md

Example of instantiating the Generator with named arguments and calling generateDocs() inside a Laravel context. Requires L5Swagger\Generator and L5Swagger\SecurityDefinitions.

```php
use L5Swagger\Generator;
use L5Swagger\SecurityDefinitions;

$generator = new Generator(
    paths: [
        'annotations' => [base_path('app')],
        'docs' => storage_path('api-docs'),
        'docs_json' => 'api-docs.json',
        'docs_yaml' => 'api-docs.yaml',
        'excludes' => [],
        'base' => '/api',
    ],
    constants: ['L5_SWAGGER_CONST_HOST' => 'https://example.com'],
    yamlCopyRequired: true,
    security: new SecurityDefinitions([], []),
    scanOptions: ['open_api_spec_version' => Generator::OPEN_API_DEFAULT_SPEC_VERSION],
);

$generator->generateDocs();
```

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

### Default Analyser Configuration with ReflectionAnalyser

Source: https://github.com/darkaonline/l5-swagger/wiki/Migration-Guides

Use this configuration to set the default analyser to use the new attribute-based system with AttributeAnnotationFactory.

```php
new \OpenApi\Analysers\ReflectionAnalyser([
    new \OpenApi\Analysers\AttributeAnnotationFactory(),
])
```

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

### Apply API Key security to endpoint

Source: https://github.com/darkaonline/l5-swagger/wiki/Examples

Applies the 'apiKey' security scheme to a GET endpoint for /api/users. The security property references the scheme name defined in the base controller.

```php
#[OA\Get(
    path: "/api/users",
    summary: "Get users",
    tags: ["Users"],
    security: [["apiKey" => []]],
    responses: [
        new OA\Response(response: 200, description: "Success")
    ]
)]
public function index()
{
    // Your code
}
```

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

### Run all tests with composer

Source: https://github.com/darkaonline/l5-swagger/blob/master/CLAUDE.md

Executes the full test suite using the phpunit script defined in composer.json.

```bash
composer run-script phpunit
```
Tokens:
Raw