### Installing Laravel OpenAPI Package via Composer

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

This command installs the `vyuldashev/laravel-openapi` package into your Laravel project using Composer. It adds the package as a dependency, making its functionalities available for use.

```bash
composer require vyuldashev/laravel-openapi
```

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

### Assigning Tags to a Laravel OpenAPI Operation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

This example demonstrates how to associate an API operation with predefined tags using the `tags` parameter in the `#[OpenApi\Operation]` attribute. By specifying `tags: ['user']`, the `store` method is logically grouped under the 'user' tag in the generated OpenAPI documentation, improving organization and navigation.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create new user.
     *
     * Creates new user or returns already existing user by email.
     */
     #[OpenApi\Operation(tags: ['user'])]
    public function store(Request $request)
    {
        //
    }
}
```

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

### Attaching Multiple OpenAPI Responses to a Route - PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This PHP example demonstrates how to define multiple possible API responses for a single controller method, each with a specific factory and HTTP status code. This ensures comprehensive API documentation covering various success and error scenarios for an endpoint.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create user.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: CreatedUserResponse::class, statusCode: 201)]
    #[OpenApi\Response(factory: ErrorUnauthenticatedResponse::class, statusCode: 401)]
    #[OpenApi\Response(factory: ErrorForbiddenResponse::class, statusCode: 401)]
    #[OpenApi\Response(factory: ErrorNotFoundResponse::class, statusCode: 404)]
    #[OpenApi\Response(factory: ErrorValidationResponse::class, statusCode: 422)]
    public function store(Request $request)
    {
        //
    }
}
```

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

### Generated OpenAPI Definition for Query Parameters

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This JSON snippet shows the OpenAPI specification generated from the `ListUsersParameters` factory and its application to the `/users` GET endpoint. It defines a 'withTrashed' query parameter with a boolean schema.

```json
{
    "paths": {
        "\/users": {
            "get": {
                "summary": "List users.",
                "parameters": [
                    {
                        "name": "withTrashed",
                        "in": "query",
                        "description": "Display trashed users too",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ]
            }
        }
    }
}
```

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

### Assigning Controller Method to a Collection in Laravel OpenAPI (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This example shows how to associate a controller method with a specific OpenAPI collection (e.g., 'v1') using the @OpenApi\Collection annotation. This allows for granular control over which API endpoints appear in different versions or subsets of the documentation.

```PHP
namespace App\Api\V1\Controllers;

use Vyuldashev\LaravelOpenApi\Annotations as OpenApi;

/**
 * @OpenApi\Collection(name = "v1")
 **/
class DemoController extends Controller
{
    /**
     * @param Request $request
     *
     * @return JsonResponse
     *
     * @OpenApi\Collection(name="v1")
     * @OpenApi\Operation(tags="demo")
     * @OpenApi\Response(factory="App\OpenApi\V1\Responses\DemoResponse", statusCode=200)
     */
    public function create(Request $request): JsonResponse
    {
        ...
    }
}
```

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

### Publishing Laravel OpenAPI Configuration File

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

This Artisan command publishes the default configuration file for the Laravel OpenAPI package to your `config` directory. This allows you to customize various settings related to OpenAPI document generation.

```bash
php artisan vendor:publish --provider="Vyuldashev\LaravelOpenApi\OpenApiServiceProvider" --tag="openapi-config"
```

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

### Generated OpenAPI Path Definition for User Creation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

This JSON snippet illustrates the resulting OpenAPI path definition generated from the PHP controller attributes. It shows how the `UserController@store` method translates into a `post` operation under the `/users` path, including the `summary` and `description` derived from the method's PHPDoc comments.

```json
{
    "paths": {
        "\/users": {
            "post": {
                "summary": "Create new user.",
                "description": "Creates new user or returns already existing user by email."
            }
        }
    }
}
```

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

### Configuring Global OpenAPI Tags in Laravel

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

This configuration snippet shows how to define global tags within the `config/openapi.php` file. Each tag includes a `name` and `description`, and can optionally link to `externalDocs` for more detailed information, enabling logical grouping and enhanced documentation for API operations.

```php
    'tags' => [

        [
           'name' => 'post',
           'description' => 'Posts',
        ],

        [
           'name' => 'user',
           'description' => 'Application users',

           // You may optionally add a link to external documentation like so:
           'externalDocs' => [
                'description' => 'External API documentation',
                'url' => 'https://example.com/external-docs',
            ],
        ],

    ],
```

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

### Manually Registering Laravel OpenAPI Service Provider

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

This PHP snippet demonstrates how to manually register the `OpenApiServiceProvider` in your `config/app.php` file. While often auto-discovered, explicit registration ensures the package's services are loaded by Laravel.

```php
'providers' => [
    // ...
    Vyuldashev\LaravelOpenApi\OpenApiServiceProvider::class,
];
```

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

### Generating Collection-Specific OpenAPI Documentation via CLI (Bash)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This command-line snippet shows how to generate OpenAPI documentation for a specific collection (e.g., 'v1') using the openapi:generate Artisan command. By providing the collection name as an argument, developers can generate documentation for different API versions or subsets from the terminal.

```Bash
php artisan openapi:generate v1
```

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

### Configuring Web Route for Collection-Specific OpenAPI Documentation (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This configuration snippet for openapi.php demonstrates how to set up a dynamic route for the OpenAPI UI, allowing specific collections to be resolved via a named route parameter (e.g., /openapi/{collection}). This enables serving different documentation versions based on the URL.

```PHP
  'route' => [
      'uri' => '/openapi/{collection}',
      'middleware' => [...],
  ],
```

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

### Generating OpenAPI Document using Artisan Command

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

This Artisan command triggers the generation of the OpenAPI document based on your project's routes and controllers. It compiles the API specification into a standard OpenAPI format.

```bash
php artisan openapi:generate
```

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

### Generating a Parameters Factory using Artisan

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This command generates a new `Parameters` object factory class, which is used to define custom query or path parameters for OpenAPI documentation. The generated class will extend `ParametersFactory`.

```bash
php artisan openapi:make-parameters ListUsers
```

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

### Generating OpenAPI Response Factory - Bash

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This command-line instruction uses the Artisan CLI to generate a new `ResponseFactory` class. The generated class, named `ListUsersResponse`, will be used to define the structure and content of an API response.

```bash
php artisan openapi:make-response ListUsers
```

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

### Handling Automatic Route Parameters in PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This PHP controller method demonstrates how Laravel OpenAPI automatically detects and documents route parameters (e.g., `{user}`). The `@param` tag is used to provide a description for the `User` parameter, which will be included in the generated OpenAPI specification without needing a separate `Parameters` attribute.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller 
{
    /**
     * Show user.
     * 
     * @param User $user User ID
     */
     #[OpenApi\Operation]
    public function show(User $user)
    {
        //
    }
}
```

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

### Defining API Operation for User Creation in Laravel OpenAPI

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

This snippet demonstrates how to include a Laravel route in the OpenAPI specification. By applying `#[OpenApi\PathItem]` to the controller class and `#[OpenApi\Operation]` to the specific action method, the route's definition (e.g., `UserController@store`) is automatically added to the `paths` section, making it discoverable and documented.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * Create new user.
     *
     * Creates new user or returns already existing user by email.
     */
     #[OpenApi\Operation]
    public function store(Request $request)
    {
        //
    }
}
```

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

### Generating OpenAPI Schema from Model (Bash)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/schemas.md

This Artisan command generates an OpenAPI schema file named 'User' by inferring its structure and properties from the specified 'User' Eloquent model. The `-m` or `--model` option links the schema generation to an existing database model.

```bash
php artisan openapi:make-schema User -m User
```

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

### Generating OpenAPI Request Body using Artisan Command (Bash)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/request-bodies.md

This command generates a new request body factory class for Laravel OpenAPI. It creates a boilerplate file that can be customized to define the structure of the request body, streamlining the API documentation process.

```bash
php artisan openapi:make-requestbody StoreUser
```

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

### Generating Basic OpenAPI Schema (Bash)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/schemas.md

This Artisan command generates a new, empty OpenAPI schema file named 'User'. This is typically used when you want to define the schema structure manually without inferring from an existing model.

```bash
php artisan openapi:make-schema User
```

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

### Generating a Security Scheme using Artisan

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/security.md

This command generates a new security scheme named 'BearerToken' using the Laravel Artisan CLI. This scheme will be declared in the `securitySchemes` section of the OpenAPI configuration, making it available for use in API security requirements.

```bash
php artisan openapi:make-security-scheme BearerToken
```

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

### Attaching a Single OpenAPI Response to a Route - PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This PHP code demonstrates how to associate a previously defined `ResponseFactory` (e.g., `ListUsersResponse`) with a controller method using the `#[OpenApi\Response]` attribute. This links the API documentation for the `index` method to the specified response definition.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * List users.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: ListUsersResponse::class)]
    public function index(User $user)
    {
        //
    }
}
```

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

### Defining a Basic OpenAPI Response - PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This PHP class extends `ResponseFactory` and defines a simple 'OK' response with a description. It's used to construct a standard successful API response for a specific endpoint.

```php
class ListUsersResponse extends ResponseFactory
{
    public function build(): Response
    {
        return Response::ok()->description('Successful response');
    }
}
```

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

### Referencing OpenAPI Schema in Laravel Response (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/schemas.md

This PHP code demonstrates how to integrate a previously defined OpenAPI schema, `UserSchema`, into an API response. The `UserSchema::ref()` method creates a reference to the schema, ensuring the response's documentation aligns with the schema definition. The `UserSchema` must implement the `Vyuldashev\LaravelOpenApi\Contracts\Reusable` contract.

```php
use App\OpenApi\Schemas\UserSchema;

class ListUsersResponse extends ResponseFactory
{
    public function build(): Response
    {
        return Response::ok()->description('Successful response')->content(
            MediaType::json()->schema(UserSchema::ref())
        );
    }
}
```

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

### Generated OpenAPI Definition for Route Parameters

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This JSON snippet illustrates the OpenAPI definition generated for a route with a path parameter, such as `/users/{user}`. The 'user' parameter is automatically identified as an 'in: path' parameter, and its description is derived from the `@param` tag in the controller method.

```json
{
    "paths": {
        "\/users\/{user}": {
            "get": {
                "summary": "Show user.",
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "description": "User ID",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        }
    }
}
```

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

### Applying Security Scheme Globally in OpenAPI Config

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/security.md

This PHP configuration snippet demonstrates how to apply a security scheme, specifically 'BearerToken', globally to all API operations within the `config/openapi.php` file. This ensures that the specified security requirement is enforced by default across the entire API.

```php
'security' => [
  GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityRequirement::create()->securityScheme('BearerToken'),
],
```

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

### Creating a Custom OpenAPI Controller for Collection Resolution (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This PHP class defines a custom OpenApiController that overrides the default behavior to accept a collection parameter. It uses the Generator to produce OpenAPI documentation specifically for the requested collection, enabling dynamic documentation serving.

```PHP
<?php

namespace App\OpenApi;

use GoldSpecDigital\ObjectOrientedOAS\OpenApi;
use Vyuldashev\LaravelOpenApi\Generator;

class OpenApiController
{
    public function show(Generator $generator, string $collection): OpenApi
    {
        return $generator->generate($collection);
    }
}
```

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

### Defining Query Parameters in PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This PHP class defines a set of query parameters for an API endpoint. It uses the `Parameter::query()` helper to specify a boolean parameter named 'withTrashed' that is optional and includes a description for documentation purposes.

```php
class ListUsersParameters extends ParametersFactory
{
    /**
     * @return Parameter[]
     */
    public function build(): array
    {
        return [

            Parameter::query()
                ->name('withTrashed')
                ->description('Display trashed users too')
                ->required(false)
                ->schema(Schema::boolean()),

        ];
    }
}
```

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

### Defining OpenAPI Request Body with Schema Reference (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/request-bodies.md

This PHP class defines an OpenAPI request body, 'UserCreate', with a description and content type. It references an external schema, 'UserSchema', using 'ref()' for reusability, ensuring consistency across API documentation.

```php
class UserCreateRequestBody extends RequestBodyFactory
{
    public function build(): RequestBody
    {
        return RequestBody::create('UserCreate')
            ->description('User data')
            ->content(
                MediaType::json()->schema(UserSchema::ref())
            );
    }
}
```

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

### Attaching Custom Parameters to a Controller Operation in PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

This PHP code demonstrates how to associate a custom `Parameters` factory (e.g., `ListUsersParameters`) with a controller method using the `#[OpenApi\Parameters]` attribute. This ensures that the defined parameters are included in the OpenAPI documentation for the `index` method.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller 
{
    /**
     * List users.
     */
    #[OpenApi\Operation]
    #[OpenApi\Parameters(factory: ListUsersParameters::class)]
    public function index() 
    {
        //
    }
}
```

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

### Using OpenAPI Request Body in a Laravel Controller (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/request-bodies.md

This Laravel controller demonstrates how to associate an OpenAPI request body with a controller method using the #[OpenApi\RequestBody] attribute. It links the 'store' method to the 'UserCreateRequestBody' factory, documenting the expected request payload for API consumers.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create a user.
     */
    #[OpenApi\Operation(tags: ['user'])]
    #[OpenApi\RequestBody(factory: UserCreateRequestBody::class)]
    public function store(Request $request)
    {
    }
}
```

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

### Overriding HTTP Method for Laravel OpenAPI Operation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

This snippet illustrates how to explicitly define the HTTP verb for an API operation using the `method` parameter within the `#[OpenApi\Operation]` attribute. This is crucial for resource controllers where a single method (e.g., `update`) might handle multiple verbs (PUT/PATCH), ensuring only the specified method (e.g., 'PATCH') is documented in OpenAPI.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Update user.
     *
     * Updates a user.
     *
     */
    #[OpenApi\Operation(tags: ['tags'], method: 'PATCH')]
    public function update(Request $request)
    {
        //
    }
}
```

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

### Applying Security Scheme to a Specific Operation in Laravel Controller

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/security.md

This PHP code snippet illustrates how to apply a specific security scheme, 'BearerTokenSecurityScheme', to an individual API operation (`store` method) within a Laravel controller using OpenApi attributes. This overrides any global security settings for this particular operation, allowing fine-grained control over API security.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * Create new user.
     *
     * Creates new user or returns already existing user by email.
     */
     #[OpenApi\Operation(security: 'BearerTokenSecurityScheme')]
    public function store(Request $request)
    {
        //
    }
}
```

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

### Binding Custom OpenAPI Controller in Laravel Service Provider (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This snippet illustrates how to bind the custom OpenApiController in a Laravel service provider's register method. This ensures that Laravel's dependency injection container uses the custom controller for the Vyuldashev\LaravelOpenApi\Http\OpenApiController interface, enabling collection-specific routing.

```PHP
<?php

namespace App\Providers;

use App\OpenApi\OpenApiController as CustomOpenApiController;
use Illuminate\Support\ServiceProvider;
use Vyuldashev\LaravelOpenApi\Http\OpenApiController;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->bind(OpenApiController::class, function ($app) {
            return $app->make(CustomOpenApiController::class);
        });
    }
}
```

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

### Attaching a Reusable OpenAPI Error Response - PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This PHP code shows how to attach a reusable `ErrorValidationResponse` to a controller method, specifically for a 422 (Unprocessable Entity) status code. This allows consistent documentation of validation errors across different API endpoints.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller
{
    /**
     * Create user.
    */
    #[OpenApi\Operation]
    #[OpenApi\Response(factory: ErrorValidationResponse::class, statusCode: 422)]
    public function store(Request $request)
    {
        //
    }
}
```

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

### Assigning Schema to a Collection in Laravel OpenAPI (PHP)

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

This snippet demonstrates how to assign an OpenAPI schema factory to a specific collection (e.g., 'v1') using the @OpenApi\Collection annotation on the class definition. This ensures that the schema is included only when generating documentation for that particular collection.

```PHP
namespace App\OpenApi\V1\Schemas;

use Vyuldashev\LaravelOpenApi\Factories\SchemaFactory;
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;
use Vyuldashev\LaravelOpenApi\Annotations as OpenApi;

/**
 * @OpenApi\Collection(name = "v1")
 **/
class QuoteOfferSchema extends SchemaFactory implements Reusable
{
    ...
}
```

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

### Defining a Reusable OpenAPI Validation Error Response - PHP

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

This PHP class defines a reusable validation error response by implementing the `Reusable` contract. It constructs a detailed JSON schema for validation errors, including a message and an object of errors, making it suitable for common error handling across multiple endpoints.

```php
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;

class ErrorValidationResponse extends ResponseFactory implements Reusable
{
    public function build(): Response
    {
        $response = Schema::object()->properties(
            Schema::string('message')->example('The given data was invalid.'),
            Schema::object('errors')
                ->additionalProperties(
                    Schema::array()->items(Schema::string())
                )
                ->example(['field' => ['Something is wrong with this field!']])
        );

        return Response::create('ErrorValidation')
            ->description('Validation errors')
            ->content(
                MediaType::json()->schema($response)
            );
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.