Laravel Swagger plugin

https://github.com/ronasit/laravel-swagger
Admin
This plugin is designed to generate documentation for your REST API during the passing PHPUnit...
Tokens:11,495
Snippets:72
Trust Score:8.4
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Laravel Swagger via Composer

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Installs the Laravel Swagger package using Composer. This is the initial step to integrate the auto-documentation feature into your Laravel project.

```bash
composer require ronasit/laravel-swagger
php artisan vendor:publish --provider=RonasIT\AutoDoc\AutoDocServiceProvider
```

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

### Configure Laravel Swagger Options

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Provides a comprehensive configuration example for Laravel Swagger, covering route definitions, API metadata, security settings, storage drivers, and documentation viewers. This file allows extensive customization of the documentation generation process.

```php
// config/auto-doc.php
return [
    // Route where documentation is served
    'route' => '/api/documentation',

    // Global URL prefix (e.g., '/api/v1')
    'global_prefix' => env('SWAGGER_GLOBAL_PREFIX', ''),

    // API metadata
    'info' => [
        'description' => 'auto-doc::swagger-description',
        'version' => '1.0.0',
        'title' => env('APP_NAME', 'My API'),
        'contact' => [
            'email' => 'api@example.com', // Required field
        ],
    ],

    // Base path for API routes
    'basePath' => '/api',

    // Security configuration (jwt, laravel, or custom)
    'security' => 'jwt',
    'security_drivers' => [
        'jwt' => [
            'type' => 'apiKey',
            'name' => 'Authorization',
            'in' => 'header',
        ],
    ],

    // Storage driver: local, remote, or storage
    'driver' => env('SWAGGER_DRIVER', 'local'),

    // Documentation viewer: swagger, elements, rapidoc, scalar
    'documentation_viewer' => env('SWAGGER_SPEC_VIEWER', 'swagger'),

    'drivers' => [
        'local' => [
            'class' => \RonasIT\AutoDoc\Drivers\LocalDriver::class,
            'production_path' => storage_path('documentation.json'),
        ],
        'storage' => [
            'class' => \RonasIT\AutoDoc\Drivers\StorageDriver::class,
            'disk' => 'public',
            'production_path' => 'documentation.json',
        ],
        'remote' => [
            'class' => \RonasIT\AutoDoc\Drivers\RemoteDriver::class,
            'key' => env('SWAGGER_REMOTE_DRIVER_KEY', 'my_project'),
            'url' => env('SWAGGER_REMOTE_DRIVER_URL', 'https://docs.example.com'),
        ],
    ],

    // Merge additional OpenAPI files
    'additional_paths' => [
        'storage/additional_docs/webhooks.json',
    ],

    // Limit response array examples
    'response_example_limit_count' => 5,

    // Environments where docs are visible
    'display_environments' => ['local', 'development', 'staging'],
];

```

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

### CI/CD Workflow for Generating and Uploading Documentation

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

This YAML configuration defines a GitHub Actions workflow for running tests and generating API documentation. It checks out the code, sets up PHP, installs dependencies, runs tests, generates documentation using `php artisan swagger:push-documentation`, and uploads the generated `documentation.json` file as an artifact.

```yaml
# .github/workflows/tests.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install Dependencies
        run: composer install --no-progress --prefer-dist

      - name: Run Tests
        run: php artisan test

      - name: Generate Documentation
        run: php artisan swagger:push-documentation

      - name: Upload Documentation
        uses: actions/upload-artifact@v4
        with:
          name: api-documentation
          path: storage/documentation.json
```

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

### GET /api/users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Retrieves a list of users. Supports filtering, pagination, and sorting.

```APIDOC
## GET /api/users

### Description
Retrieves a list of users. Supports filtering, pagination, and sorting.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **search** (string) - Optional - Filters users by name or email.
- **status** (string) - Optional - Filters users by their active status (e.g., 'active', 'inactive').
- **per_page** (integer) - Optional - The number of users to return per page.
- **sort_by** (string) - Optional - The field to sort users by (e.g., 'name', 'email').
- **sort_order** (string) - Optional - The order of sorting ('asc' or 'desc').

### Response
#### Success Response (200)
- **data** (array) - An array of user objects.
  - **id** (integer) - The unique identifier of the user.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.
  - **is_active** (boolean) - Indicates if the user account is active.
- **current_page** (integer) - The current page number of the results.
- **total** (integer) - The total number of users available.

#### Response Example
```json
{
    "data": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com",
            "is_active": true
        },
        {
            "id": 2,
            "name": "Jane Smith",
            "email": "jane@example.com",
            "is_active": false
        }
    ],
    "current_page": 1,
    "total": 10
}
```
```

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

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

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Retrieves a specific user by their ID.

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

### Description
Retrieves a specific user by their ID.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the user
- **name** (string) - The full name of the user
- **email** (string) - The email address of the user
- **role_id** (integer) - The role ID assigned to the user
- **is_active** (boolean) - Indicates if the user is active
- **created_at** (datetime) - Timestamp of user creation
- **updated_at** (datetime) - Timestamp of last user update

#### Response Example
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "role_id": 1,
  "is_active": true,
  "created_at": "2023-10-27T10:00:00.000000Z",
  "updated_at": "2023-10-27T10:00:00.000000Z"
}
```
```

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

### GET /api/users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Retrieves a paginated list of users with optional filtering and sorting capabilities.

```APIDOC
## GET /api/users

### Description
Retrieve a paginated list of users with optional filtering and sorting.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term for name or email
- **status** (string) - Optional - Filter by active/inactive status (`active`, `inactive`, `all`)
- **per_page** (integer) - Optional - Number of users per page (min: 1, max: 100)
- **sort_by** (string) - Optional - Field to sort by (`name`, `email`, `created_at`)
- **sort_order** (string) - Optional - Order of sorting (`asc`, `desc`)

### Response
#### Success Response (200)
- **data** (array) - Array of user objects
- **current_page** (integer) - Current page number
- **last_page** (integer) - Last page number
- **per_page** (integer) - Number of items per page
- **total** (integer) - Total number of users

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "is_active": true,
      "created_at": "2023-10-27T10:00:00.000000Z",
      "updated_at": "2023-10-27T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 5,
  "per_page": 15,
  "total": 75
}
```
```

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

### GET /users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Retrieves a list of users. Supports filtering by name or email. Note: This endpoint is deprecated.

```APIDOC
## GET /users

### Description
Retrieves a list of users with optional filtering.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term for name or email

### Response
#### Success Response (200)
- **users** (array) - Description of the users array structure (details would be in components/schemas/getUsersObject)

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

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

### Generate and Push Documentation with Artisan CLI

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

This snippet demonstrates how to use Artisan commands to generate and push API documentation. It's typically used within CI/CD pipelines after tests have been executed. The `swagger:push-documentation` command collects and saves the documentation to a file.

```bash
# Run tests and generate documentation
php artisan test

# Push collected documentation to storage
php artisan swagger:push-documentation
```

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

### Bash Commands to Access Generated API Documentation

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

These bash commands show how to access the generated API documentation. The first command retrieves the rendered documentation, typically served via Swagger UI, Elements, RapiDoc, or Scalar. The second command fetches the raw OpenAPI JSON specification.

```bash
# View rendered documentation (Swagger UI, Elements, RapiDoc, or Scalar)
curl http://localhost/api/documentation

# Get raw OpenAPI JSON specification
curl http://localhost/auto-doc/documentation

```

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

### Initialize Swagger UI with JavaScript

Source: https://github.com/ronasit/laravel-swagger/blob/master/tests/fixtures/AutoDocControllerTest/rendered_documentation.html

Initializes the Swagger UI component using SwaggerUIBundle. It fetches API documentation from a dynamically generated URL and configures deep linking, model rendering, and includes essential presets and plugins for a standalone layout. This script should be included in your HTML file where the Swagger UI is intended to be displayed.

```javascript
const prefix = ''; window.onload = () => {
  const ui = SwaggerUIBundle({
    url: `${prefix}/auto-doc/documentation`,
    dom_id: '#swagger-ui',
    deepLinking: true,
    defaultModelRendering: 'model',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: 'StandaloneLayout'
  });
  window.ui = ui;
}
```

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

### Register AutoDocMiddleware in Global HTTP Middleware

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

To enable the documentation generation, register the AutoDocMiddleware in the global HTTP middleware list within your `bootstrap/app.php` file. This middleware intercepts requests to facilitate documentation collection.

```php
    return Application::configure(basePath: dirname(__DIR__))
        ->withMiddleware(function (Middleware $middleware) {
            $middleware->use([
                ...
                \RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
            ]);
        });

```

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

### POST /users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Creates a new user account. Requires user details in the request body.

```APIDOC
## POST /users

### Description
Creates a new user account.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **name** (string) - Required - Full name
- **email** (string) - Required - Email address
- **password** (string) - Required - User's password
- **role_id** (integer) - Required - Role identifier

### Request Example
```json
{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "password": "securepassword123",
  "role_id": 1
}
```

### Response
#### Success Response (201)
- **message** (string) - Indicates successful user creation.

#### Error Response (422)
- **errors** (object) - Contains validation errors if the request body is invalid.

#### Response Example (201)
```json
{
  "message": "User created successfully"
}
```
```

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

### POST /api/users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Creates a new user in the system. Requires user details in the request body.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system. Requires user details in the request body.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **name** (string) - Required - The name of the user.
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The password for the user.
- **role_id** (integer) - Required - The ID of the role assigned to the user.
- **is_active** (boolean) - Optional - Indicates if the user account is active.

### Request Example
```json
{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "SecurePass123",
    "role_id": 1,
    "is_active": true
}
```

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier of the created user.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.
- **role_id** (integer) - The ID of the role assigned to the user.
- **is_active** (boolean) - Indicates if the user account is active.
- **created_at** (string) - The timestamp when the user was created.
- **updated_at** (string) - The timestamp when the user was last updated.

#### Response Example
```json
{
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role_id": 1,
    "is_active": true,
    "created_at": "2023-10-27T10:00:00.000000Z",
    "updated_at": "2023-10-27T10:00:00.000000Z"
}
```

#### Error Response (422)
- **message** (string) - A message indicating validation failure.
- **errors** (object) - An object containing validation errors for each field.
```

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

### POST /api/users

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Creates a new user account in the system. The email must be unique. Returns the created user object with an assigned ID.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system. The email must be unique. Returns the created user object with assigned ID.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **name** (string) - Required - The full name of the user
- **email** (string) - Required - User's email address (must be unique)
- **password** (string) - Required - Minimum 8 characters with mixed case
- **role_id** (integer) - Required - Reference to the user's role
- **is_active** (boolean) - Optional - Indicates if the user is active
- **metadata** (array) - Optional - Additional metadata for the user

### Request Example
```json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "password": "Password123",
  "role_id": 1,
  "is_active": true,
  "metadata": {
    "key": "value"
  }
}
```

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier of the created user
- **name** (string) - The full name of the user
- **email** (string) - The email address of the user
- **role_id** (integer) - The role ID assigned to the user
- **is_active** (boolean) - Indicates if the user is active
- **created_at** (datetime) - Timestamp of user creation
- **updated_at** (datetime) - Timestamp of last user update

#### Response Example
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "role_id": 1,
  "is_active": true,
  "created_at": "2023-10-27T10:00:00.000000Z",
  "updated_at": "2023-10-27T10:00:00.000000Z"
}
```

#### Error Response (422)
- **message** (string) - Error message indicating validation failure
- **errors** (object) - Object containing validation errors for each field
```

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

### Webhooks API

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Documentation for the payment received webhook, called by the payment provider when payment is confirmed.

```APIDOC
## POST /webhooks/payment-received

### Description
Called by payment provider when payment is confirmed

### Method
POST

### Endpoint
/webhooks/payment-received

### Parameters
#### Request Body
- **transaction_id** (string) - Required - The ID of the transaction.
- **amount** (number) - Required - The amount of the payment.
- **currency** (string) - Required - The currency of the payment.
- **status** (string) - Required - The status of the payment. Enum: `completed`, `failed`, `pending`

### Request Example
{
  "transaction_id": "txn_12345",
  "amount": 100.50,
  "currency": "USD",
  "status": "completed"
}

### Response
#### Success Response (200)
- **message** (string) - Indicates that the webhook was processed successfully.

#### Response Example
{
  "message": "Webhook processed"
}
```

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

### Configuration for Custom S3 Driver in Laravel

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

This configuration snippet shows how to register and configure a custom S3 driver for API documentation within a Laravel application. It involves defining the driver class, S3 credentials, bucket name, and path in `config/auto-doc.php`. The active driver is then set using an environment variable.

```php
// config/auto-doc.php - Register custom driver
'drivers' => [
    's3' => [
        'class' => \App\Services\Swagger\S3Driver::class,
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'bucket' => env('AWS_DOCS_BUCKET', 'api-documentation'),
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'path' => 'docs/api-spec.json',
    ],
],

// Set as active driver
'driver' => env('SWAGGER_DRIVER', 's3'),

```

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

### Document User Creation Request with Annotations (PHP)

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Defines a FormRequest class for creating users, using PHPDoc annotations to describe parameters, validation rules, and API responses. This enables automatic generation of Swagger documentation for the user creation endpoint.

```php
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

/**
 * @summary Create a new user account
 *
 * @description
 * Creates a new user in the system. The email must be unique.
 * Returns the created user object with assigned ID.
 *
 * @_201 User created successfully
 * @_422 Validation failed
 *
 * @name The full name of the user
 * @email User's email address (must be unique)
 * @password Minimum 8 characters with mixed case
 * @role_id Reference to the user's role
 */
class CreateUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:8',
            'role_id' => 'required|integer|exists:roles,id',
            'is_active' => 'boolean',
            'metadata' => 'array|nullable',
        ];
    }

    public function attributes(): array
    {
        return [
            'name' => 'Full name',
            'email' => 'Email address',
            'role_id' => 'Role identifier',
        ];
    }
}

```

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

### Merge Additional OpenAPI Documentation Files

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Combine auto-generated OpenAPI specifications with manually created documentation files. This is configured in `config/auto-doc.php` by specifying paths to additional JSON files.

```json
// storage/additional_docs/webhooks.json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Webhooks",
    "version": "1.0.0"
  },
  "paths": {
    "/webhooks/payment-received": {
      "post": {
        "tags": ["webhooks"],
        "summary": "Payment received webhook",
        "description": "Called by payment provider when payment is confirmed",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentWebhook"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PaymentWebhook": {
        "type": "object",
        "properties": {
          "transaction_id": {"type": "string"},
          "amount": {"type": "number"},
          "currency": {"type": "string"},
          "status": {"type": "string", "enum": ["completed", "failed", "pending"]}
        }
      }
    }
  }
}
```

```php
// config/auto-doc.php
'additional_paths' => [
    'storage/additional_docs/webhooks.json',
    'storage/additional_docs/admin-api.json',
],
```

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

### Configure Swagger UI Bundle in JavaScript

Source: https://github.com/ronasit/laravel-swagger/blob/master/tests/fixtures/AutoDocControllerTest/rendered_documentation_with_global_path.html

This JavaScript code configures the Swagger UI bundle, specifying the API documentation URL, the DOM element for rendering, and various UI preferences. It utilizes the SwaggerUIBundle function to initialize the interface, enabling features like deep linking and model rendering.

```javascript
const prefix = '/global';
window.onload = () => {
  const ui = SwaggerUIBundle({
    url: `${prefix}/auto-doc/documentation`,
    dom_id: '#swagger-ui',
    deepLinking: true,
    defaultModelRendering: 'model',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: 'StandaloneLayout'
  });
  window.ui = ui;
}
```

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

### Basic HTML Structure for Swagger UI

Source: https://github.com/ronasit/laravel-swagger/blob/master/tests/fixtures/AutoDocControllerTest/rendered_documentation_with_global_path.html

This HTML and CSS code provides the fundamental structure for rendering the Swagger UI. It includes basic styling for the HTML element and a universal selector to ensure consistent box-sizing, preparing the page to host the interactive API documentation.

```html
html {
  box-sizing: border-box;
  overflow: -moz-scrollbars-vertical;
  overflow-y: scroll;
}

*, *:before, *:after {
  box-sizing: inherit;
}

body {
  margin: 0;
  background: #fafafa;
}
```

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

### Create Controller Method for User Update (PHP)

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

Implements a controller method that utilizes dependency injection for the `UpdateUserDataRequest` to process user data updates. The method returns an HTTP 204 No Content response upon successful execution.

```php
<?php

namespace App\Http\Controllers;

use App\Http\Requests\Users\UpdateUserDataRequest;

class UserController extends Controller
{
    public function update(UpdateUserDataRequest $request, UserService $service, $id)
    {
        // do something here...

        return response('', Response::HTTP_NO_CONTENT);
    }
}

```

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

### SwaggerService Core Methods

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Core methods of the SwaggerService class for generating and managing API documentation.

```APIDOC
## SwaggerService Core Methods

### Description
The SwaggerService class provides the main documentation generation functionality.

### Methods

#### `getDocFileContent()`
**Description**: Retrieves the compiled documentation, merging auto-generated content with additional files.
**Returns**: An array structure containing the OpenAPI documentation.

#### `saveProductionData()`
**Description**: Saves the generated documentation to the configured storage driver.

#### `addData($request, $response)`
**Description**: Adds request and response data during test execution. This method is typically called by the package's middleware.
```

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

### Configure SwaggerExtension in PHPUnit XML

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

Configure your `phpunit.xml` file to include the SwaggerExtension. This method is a traditional way to integrate the documentation generation with PHPUnit tests. Note that this approach may be deprecated in future PHPUnit versions.

```xml
<phpunit>
    <extensions>
        <bootstrap class="RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension"/>
    </extensions>
    <testsuites>
        <testsuite name="Feature">
            <directory suffix="Test.php">./tests/Feature</directory>
        </testsuite>
    </testsuites>
</phpunit>

```

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

### Document User Listing Request with Annotations (PHP)

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Defines a FormRequest for listing users, incorporating annotations for search parameters, status filters, and pagination options. This request class helps in generating Swagger documentation for user retrieval endpoints, including filtering and sorting capabilities.

```php
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

/**
 * @summary List users with filters
 *
 * @description
 * Retrieve a paginated list of users with optional filtering and sorting.
 *
 * @_200 Users retrieved successfully
 *
 * @deprecated
 *
 * @search Search term for name or email
 * @status Filter by active/inactive status
 */
class ListUsersRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'search' => 'string|nullable',
            'status' => 'in:active,inactive,all',
            'per_page' => 'integer|min:1|max:100',
            'sort_by' => 'string|in:name,email,created_at',
            'sort_order' => 'string|in:asc,desc',
        ];
    }
}

```

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

### Add AutoDocServiceProvider to Laravel App Config

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

For older Laravel versions (prior to 5.5), you need to manually add the AutoDocServiceProvider to the providers array in your `config/app.php` file. This ensures the package's service provider is registered.

```php
        'providers' => [
            ...
            RonasIT\AutoDoc\AutoDocServiceProvider::class,
        ],
```

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

### Controller with FormRequest Injection for API Operations (PHP)

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Demonstrates a Laravel controller that utilizes FormRequest classes for handling incoming HTTP requests. By injecting `CreateUserRequest` and `ListUsersRequest`, the controller benefits from automatic validation and documented parameters, simplifying API development and Swagger generation.

```php
<?php

namespace App\Http\Controllers;

use App\Http\Requests\CreateUserRequest;
use App\Http\Requests\ListUsersRequest;
use App\Http\Requests\UpdateUserRequest;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;

class UserController extends Controller
{
    public function index(ListUsersRequest $request): JsonResponse
    {
        $users = User::query()
            ->when($request->search, fn($q, $search) =>
                $q->where('name', 'like', "%{$search}%")
                  ->orWhere('email', 'like', "%{$search}%")
            )
            ->when($request->status !== 'all', fn($q) =>
                $q->where('is_active', $request->status === 'active')
            )
            ->orderBy($request->sort_by ?? 'created_at', $request->sort_order ?? 'desc')
            ->paginate($request->per_page ?? 15);

        return response()->json($users);
    }

    public function store(CreateUserRequest $request): JsonResponse
    {
        $user = User::create($request->validated());

        return response()->json($user, Response::HTTP_CREATED);
    }

    public function show(int $id): JsonResponse
    {
        $user = User::findOrFail($id);

        return response()->json($user);
    }

    public function update(UpdateUserRequest $request, int $id): JsonResponse
    {
        $user = User::findOrFail($id);
        $user->update($request->validated());

        return response()->json($user);
    }

    public function destroy(int $id): Response
    {
        User::findOrFail($id)->delete();

        return response('', Response::HTTP_NO_CONTENT);
    }
}

```

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

### Add AutoDocTestCaseTrait to TestCase

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

Include the AutoDocTestCaseTrait in your `tests/TestCase.php` file. This trait provides the necessary functionality for the Laravel Swagger plugin to interact with your test cases for documentation generation.

```php
use RonasITAutoDocTraitsAutoDocTestCaseTrait;

// ... inside your TestCase class
    use AutoDocTestCaseTrait;

```

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

### Custom S3 Storage Driver for API Documentation

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

This PHP code implements a custom storage driver for API documentation using AWS S3. It extends `BaseDriver` and implements `SwaggerDriverContract`, allowing documentation to be saved to and retrieved from an S3 bucket. Dependencies include the AWS SDK for PHP.

```php
<?php

namespace App\Services\Swagger;

use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
use RonasIT\AutoDoc\Drivers\BaseDriver;
use Aws\S3\S3Client;

class S3Driver extends BaseDriver implements SwaggerDriverContract
{
    protected S3Client $client;
    protected string $bucket;
    protected string $key;

    public function __construct()
    {
        parent::__construct();

        $this->client = new S3Client([
            'version' => 'latest',
            'region' => config('auto-doc.drivers.s3.region'),
            'credentials' => [
                'key' => config('auto-doc.drivers.s3.key'),
                'secret' => config('auto-doc.drivers.s3.secret'),
            ],
        ]);

        $this->bucket = config('auto-doc.drivers.s3.bucket');
        $this->key = config('auto-doc.drivers.s3.path', 'documentation.json');
    }

    public function saveData(): void
    {
        $this->client->putObject([
            'Bucket' => $this->bucket,
            'Key' => $this->key,
            'Body' => json_encode($this->getTmpData()),
            'ContentType' => 'application/json',
        ]);

        $this->clearProcessTmpData();
    }

    public function getDocumentation(): array
    {
        $result = $this->client->getObject([
            'Bucket' => $this->bucket,
            'Key' => $this->key,
        ]);

        $content = (string) $result['Body'];

        if (empty($content)) {
            throw new \RonasIT\AutoDoc\Exceptions\EmptyDocFileException($this->key);
        }

        return json_decode($content, true);
    }
}

```

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

### SwaggerService Core Methods for Documentation Generation

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

The `SwaggerService` class in Laravel Swagger provides core functionality for generating and managing API documentation. It allows retrieving compiled documentation, saving it to configured storage, and adding request/response data during test execution.

```php
<?php

use RonasIT\AutoDoc\Services\SwaggerService;

// Get the service instance
$service = app(SwaggerService::class);

// Get compiled documentation (merges auto-generated with additional files)
$documentation = $service->getDocFileContent();

// Returns array structure:
// [
//     'openapi' => '3.1.0',
//     'info' => [...],
//     'servers' => [...],
//     'paths' => [...],
//     'components' => ['schemas' => [...]],
// ]

// Save documentation to configured storage driver
$service->saveProductionData();

// During test execution, add request/response data (called by middleware)
// $service->addData($request, $response);

```

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

### Create API Endpoint Test (PHP)

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

A PHPUnit test method to verify the functionality of the user update API endpoint. It sends a PUT request with sample data and asserts that the response status code is 204 (No Content).

```php
public function testUpdate()
{
    $response = $this->json('put', '/users/1', [
        'name': 'Updated User',
        'is_active': true,
        'age': 22
    ]);

    $response->assertStatus(Response::HTTP_NO_CONTENT);
}

```

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

### PUT /api/users/{id}

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Updates an existing user's information by their ID.

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

### Description
Updates an existing user's information by their ID.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user to update

#### Request Body
- **name** (string) - Optional - The full name of the user
- **email** (string) - Optional - User's email address
- **password** (string) - Optional - Minimum 8 characters with mixed case
- **role_id** (integer) - Optional - Reference to the user's role
- **is_active** (boolean) - Optional - Indicates if the user is active
- **metadata** (array) - Optional - Additional metadata for the user

### Request Example
```json
{
  "is_active": false
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the updated user
- **name** (string) - The full name of the user
- **email** (string) - The email address of the user
- **role_id** (integer) - The role ID assigned to the user
- **is_active** (boolean) - Indicates if the user is active
- **created_at** (datetime) - Timestamp of user creation
- **updated_at** (datetime) - Timestamp of last user update

#### Response Example
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "role_id": 1,
  "is_active": false,
  "created_at": "2023-10-27T10:00:00.000000Z",
  "updated_at": "2023-10-27T10:05:00.000000Z"
}
```
```

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

### Register AutoDoc Middleware in Laravel

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Registers the AutoDocMiddleware in your Laravel application's bootstrap process. This middleware is responsible for intercepting requests and responses during testing to gather documentation data.

```php
// bootstrap/app.php - Register the middleware
return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->use([
            \RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
        ]);
    });

```

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

### DELETE /api/users/{id}

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Deletes a user from the system. Requires the user ID in the path.

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

### Description
Deletes a user from the system. Requires the user ID in the path.

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user to delete.

### Response
#### Success Response (204)
No content is returned upon successful deletion.
```

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

### Create Request Class for User Data Update (PHP)

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

Defines a FormRequest class to handle user data updates, including validation rules and annotations for Swagger documentation. This class is essential for generating API documentation fields and descriptions.

```php
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

/**
* @summary Update user
*
* @deprecated 
*
* @description
* This request should be used for updating the user data
*
* @_204 Successful
*
* @is_active will indicate whether the user is active or not
*/
class UpdateUserDataRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }

    /**
     * Validation Rules
     *
     * @return array
     */
    public function rules()
    {
        return [
            'name' => 'string',
            'is_active' => 'boolean',
            'age' => 'integer|nullable'
        ];
    }
}

```

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

### Update User API Endpoint

Source: https://github.com/ronasit/laravel-swagger/blob/master/readme.md

This endpoint allows for updating user data. It uses a dedicated request class for validation and documentation generation. The response for a successful update is a 204 No Content.

```APIDOC
## PUT /users/{id}

### Description
Updates the data for a specific user identified by their ID.

### Method
PUT

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user to update.

#### Request Body
- **name** (string) - Optional - The updated name of the user.
- **is_active** (boolean) - Optional - Indicates whether the user is active.
- **age** (integer) - Optional - The updated age of the user.

### Request Example
```json
{
    "name": "Updated User",
    "is_active": true,
    "age": 22
}
```

### Response
#### Success Response (204)
- **description** - Indicates a successful update with no content returned.

#### Response Example
```json
""
```
```

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

### PHP Feature Tests for User API Endpoints

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

These PHP feature tests use Laravel's testing utilities to interact with the user API endpoints. They cover creating, listing, updating, and deleting users, as well as testing validation errors. The tests assert the status codes and JSON structures of the responses, ensuring API correctness and providing data for documentation generation.

```php
<?php

namespace Tests\Feature;

use App\Models\User;
use App\Models\Role;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class UserControllerTest extends TestCase
{
    use RefreshDatabase;

    public function testCreateUser(): void
    {
        $role = Role::factory()->create();

        $response = $this->json('POST', '/api/users', [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'password' => 'SecurePass123',
            'role_id' => $role->id,
            'is_active' => true,
        ]);

        $response->assertStatus(201)
            ->assertJsonStructure([
                'id',
                'name',
                'email',
                'role_id',
                'is_active',
                'created_at',
                'updated_at',
            ]);
    }

    public function testListUsers(): void
    {
        User::factory()->count(5)->create();

        $response = $this->json('GET', '/api/users', [
            'search' => 'john',
            'status' => 'active',
            'per_page' => 10,
            'sort_by' => 'name',
            'sort_order' => 'asc',
        ]);

        $response->assertStatus(200)
            ->assertJsonStructure([
                'data' => [
                    '*' => ['id', 'name', 'email', 'is_active'],
                ],
                'current_page',
                'total',
            ]);
    }

    public function testUpdateUser(): void
    {
        $user = User::factory()->create();

        $response = $this->json('PUT', "/api/users/{$user->id}", [
            'name' => 'Updated Name',
            'is_active' => false,
        ]);

        $response->assertStatus(200)
            ->assertJson([
                'id' => $user->id,
                'name' => 'Updated Name',
                'is_active' => false,
            ]);
    }

    public function testDeleteUser(): void
    {
        $user = User::factory()->create();

        $response = $this->json('DELETE', "/api/users/{$user->id}");

        $response->assertStatus(204);
    }

    public function testCreateUserValidationError(): void
    {
        $response = $this->json('POST', '/api/users', [
            'name' => '',
            'email' => 'invalid-email',
        ]);

        $response->assertStatus(422)
            ->assertJsonValidationErrors(['name', 'email', 'password', 'role_id']);
    }
}

```

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

### DELETE /api/users/{id}

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Deletes a user by their ID.

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

### Description
Deletes a user by their ID.

### Method
DELETE

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

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user to delete

### Response
#### Success Response (204)
No content is returned upon successful deletion.
```

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

### PUT /api/users/{id}

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

Updates an existing user's information. Requires the user ID in the path and fields to update in the request body.

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

### Description
Updates an existing user's information. Requires the user ID in the path and fields to update in the request body.

### Method
PUT

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

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user to update.

#### Request Body
- **name** (string) - Optional - The updated name of the user.
- **is_active** (boolean) - Optional - The updated status of the user account.

### Request Example
```json
{
    "name": "Updated Name",
    "is_active": false
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the updated user.
- **name** (string) - The updated name of the user.
- **is_active** (boolean) - The updated status of the user account.

#### Response Example
```json
{
    "id": 1,
    "name": "Updated Name",
    "is_active": false
}
```
```

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

### PHP Feature Tests to Skip Documentation Collection

Source: https://context7.com/ronasit/laravel-swagger/llms.txt

These PHP feature tests demonstrate how to use the `skipDocumentationCollecting()` trait method to exclude specific API endpoints from being documented. This is useful for internal or health check endpoints that should not appear in public API documentation.

```php
<?php

namespace Tests\Feature;

use Tests\TestCase;

class InternalApiTest extends TestCase
{
    public function testHealthCheck(): void
    {
        // Skip this test from documentation
        $this->skipDocumentationCollecting();

        $response = $this->get('/api/health');

        $response->assertStatus(200);
    }

    public function testInternalMetrics(): void
    {
        // This endpoint should not appear in public docs
        $this->skipDocumentationCollecting();

        $response = $this->json('GET', '/api/internal/metrics');

        $response->assertStatus(200);
    }
}

```

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

### Validate Operation Parameters - SwaggerSpecValidator (PHP)

Source: https://github.com/ronasit/laravel-swagger/blob/master/tests/fixtures/SwaggerServiceTest/invalid_format_file_no_consumes.html

This PHP code snippet from SwaggerSpecValidator.php is responsible for validating Swagger specifications. It specifically checks if an API operation incorrectly defines both 'body' and 'formData' parameters, throwing an InvalidSwaggerSpecException if this rule is violated. The function `validateFormDataConsumes` is where this validation occurs.

```php
<?php

namespace RonasIT\AutoDoc\Validators;

use RonasIT\AutoDoc\Exceptions\SpecValidation\InvalidSwaggerSpecException;

class SwaggerSpecValidator
{
    // ... other methods

    protected function validateFormDataConsumes(array $operation, string $path) 
    {
        $hasBody = false;
        $hasFormData = false;

        foreach ($operation['parameters'] as $parameter) {
            if (isset($parameter['in'])) {
                if ($parameter['in'] === 'body') {
                    $hasBody = true;
                } elseif ($parameter['in'] === 'formData') {
                    $hasFormData = true;
                }
            }
        }

        if ($hasBody && $hasFormData) {
            throw new InvalidSwaggerSpecException(
                sprintf(
                    'Validation failed. Operation '%s' has body and formData parameters. Only one or the other is allowed.',
                    $path
                )
            );
        }
    }

    // ... other methods
}

```
Tokens:
Raw