# Operations

Routes are not automatically added to specification.

In order to add route, you need to add PathItem attribute to controller class and Operation to particular action method. This attribute will indicate that route which has UserController@store definition should be included in paths.

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

The following definition will be generated:

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

# Security

See Security.

# Tags

Tags can be used for logical grouping of operations by resources or any other qualifier.

To use tags, first set them up in config/openapi.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',
            ],
        ],

    ],

Then add them using in the Operation attribute on your controller:

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

# Manual Operation Builders

Use operation builders when you need to assemble an operation manually:

use Vyuldashev\LaravelOpenApi\Builders\ExternalDocs;
use Vyuldashev\LaravelOpenApi\Builders\Operation;
use Vyuldashev\LaravelOpenApi\Builders\Response;
use Vyuldashev\LaravelOpenApi\Builders\Server;

return Operation::post()
    ->summary('Create user')
    ->description('Creates a user.')
    ->tags('user')
    ->externalDocs(
        ExternalDocs::create()->url('https://example.com/docs/users')
    )
    ->servers(
        Server::create()->url('https://api.example.com')
    )
    ->responses(
        Response::created()->description('Created')
    );

Available operation constructors are get(), post(), put(), patch(), delete(), options(), head(), and trace(). Use action('patch') to change the HTTP method on an existing builder.

Operation::responses(), parameters(), requestBody(), callbacks(), and servers() accept package builders. Operation::security() accepts OpenAPI security requirement maps, and noSecurity() emits an empty operation security override.

# Manual Path Items

Use PathItem builders to attach operations to HTTP verbs:

use Vyuldashev\LaravelOpenApi\Builders\Operation;
use Vyuldashev\LaravelOpenApi\Builders\PathItem;
use Vyuldashev\LaravelOpenApi\Builders\Response;

return PathItem::create()
    ->route('/users')
    ->summary('Users')
    ->description('User operations')
    ->post(
        Operation::post()->responses(Response::created())
    );

PathItem supports get(), post(), put(), patch(), delete(), options(), head(), and trace().

# Resource Controllers and Multiple HTTP Verbs

When using resource controllers (opens new window), the update method accepts both PUT and PATCH requests.

When a controller method accepts multiple methods, by default only the first is included in the generated documentation.

To override which verb or method should be used on a particular operation, add the method parameter the Operation attribute on your controller:

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

← Introduction Parameters →