vyuldashev/laravel-openapi

Collections allow you to declare and manage multiple distinct OpenAPI document configurations within a single Laravel application. By default, the openapi.php configuration file contains a single collection named default.

You can define additional collections by adding entries to the collections array in your openapi.php config file, where the key is the name of the collection.

To ensure specific components are included in a particular collection, use the @OpenApi\Collection annotation on your classes (Schemas) or controller methods.

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

For standard Laravel route parameters (e.g., /users/{user}), you do not need to manually create a Parameters factory. The package automatically detects route parameters from the controller method arguments.

To add a description to a route parameter in the generated OpenAPI spec, use the @param PHPDoc tag in the method's docblock.

Example:

use Vyuldashev\\LaravelOpenApi\Attributes as OpenApi;

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

use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

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

Path middlewares allow you to transform OpenAPI data at specific lifecycle points during the generation process.

To implement a path middleware:

1. Create a class that implements \Vyuldashev\LaravelOpenApi\Contracts\PathMiddleware.
2. Register the class in your configuration file under the openapi.collections.default.middlewares.paths array using its fully qualified class name.

Available lifecycle points:

• before: Triggered after all RouteInformation has been collected, but before they are processed.
• after: Triggered after the PathItem has been built.

// In your config/openapi.php
'collections' => [
    'default' => [
        'middlewares' => [
            'paths' => [
                MyPathMiddleware::class,
            ],
        ],
    ],
],

Use the openapi:make-security-scheme Artisan command to generate a new security scheme. This will declare the scheme in the securitySchemes section of your OpenAPI specification.

Example command:

php artisan openapi:make-security-scheme BearerToken

Routes are not automatically included in the generated OpenAPI specification. To include a route, you must apply two attributes:

1. #[OpenApi\\PathItem] on the controller class.
2. #[OpenApi\Operation] on the specific action method.

The summary and description fields in the generated OpenAPI paths object are derived from the DocBlock comments of the controller method.

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)
    {
        //
    }
}

Component middlewares allow you to transform OpenAPI components (like schemas or security schemes) after they have been constructed.

To implement a component middleware:

1. Create a class that implements \Vyuldashev\LaravelOpenApi\Contracts\ComponentMiddleware.
2. Register the class in your configuration file under the openapi.collections.default.middlewares.components array using its fully qualified class name.

Available lifecycle points:

• after: Triggered after the Components object has been built.

// In your config/openapi.php
'collections' => [
    'default' => [
        'middlewares' => [
            'components' => [
                MyComponentMiddleware::class,
            ],
        ],
    ],
],

To apply a specific security scheme to a single API endpoint, use the #[OpenApi\\]Operation attribute on the controller method. Pass the name of the security scheme to the security parameter.

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)
    {
        //
    }
}

To define an OpenAPI response, first generate a new response factory using the Artisan command. Then, extend the ResponseFactory class and implement the build() method, which must return a Response object.

1. Generate the factory: php artisan openapi:make-response Name

2. Implement the build() method in the generated class.

php artisan openapi:make-response ListUsers

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

When a controller method handles multiple HTTP verbs (common in Laravel resource controllers where update might handle both PUT and PATCH), the generator defaults to including only the first method.

To specify a specific HTTP verb for an operation, use the method parameter in the #[OpenApi\Operation] attribute.

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)
    {
        //
    }
}