Add operation optional elements

docs/paths/operations.md

@@ -12,11 +12,13 @@ use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;
 class UserController extends Controller
 {
     /**
-     * Create new user.
+     * The first comment here will serve as the summary.
      *
-     * Creates new user or returns already existing user by email.
+     * The second comment will be used as the description.
+     * 
+     * @deprecated This endpoint is deprecated.
      */
-     #[OpenApi\Operation]
+    #[OpenApi\Operation]
     public function store(Request $request)
     {
         //
@@ -31,14 +33,21 @@ The following definition will be generated:
     "paths": {
         "\/users": {
             "post": {
-                "summary": "Create new user.",
-                "description": "Creates new user or returns already existing user by email."
+                "summary": "Get all users",
+                "description": "Get all users from the database.",
+                "deprecated": true
             }
         }
     }
 }
 ```
 
+Alternatively, you can achieve the same result by using the Operation attribute directly:
+
+```php
+#[OpenApi\Operation(summary: 'Get all users', description: 'Get all users from the database.', deprecated: true)]
+```
+
 ## Security
 
 See [Security](../security.md#operation-level-example)

examples/petstore/PetController.php

@@ -12,7 +12,7 @@ class PetController
     /**
      * List all pets.
      */
-    #[OpenApi\Operation('listPets')]
+    #[OpenApi\Operation(id: 'listPets', summary: 'List all pets.', description: 'List all pets from the database.', deprecated: true)]
     #[OpenApi\Parameters(ListPetsParameters::class)]
     #[OpenApi\Response(ErrorValidationResponse::class, 422)]
     public function index()

src/Attributes/Operation.php

@@ -20,20 +20,33 @@ class Operation
 
     public ?array $servers;
 
+    public ?string $summary;
+
+    public ?string $description;
+
+    public ?bool $deprecated;
+
     /**
-     * @param  string|null  $id
-     * @param  array  $tags
-     * @param  \Vyuldashev\LaravelOpenApi\Factories\SecuritySchemeFactory|string|null  $security
-     * @param  string|null  $method
+     * @param string|null $id
+     * @param array $tags
+     * @param \Vyuldashev\LaravelOpenApi\Factories\SecuritySchemeFactory|string|null $security
+     * @param string|null $method
+     * @param array|null $servers
+     * @param string|null $summary
+     * @param string|null $description
+     * @param bool|null $deprecated
      *
      * @throws InvalidArgumentException
      */
-    public function __construct(string $id = null, array $tags = [], string $security = null, string $method = null, array $servers = null)
+    public function __construct(string $id = null, array $tags = [], string $security = null, string $method = null, array $servers = null, string $summary = null, string $description = null, bool $deprecated = null)
     {
         $this->id = $id;
         $this->tags = $tags;
         $this->method = $method;
         $this->servers = $servers;
+        $this->summary = $summary;
+        $this->description = $description;
+        $this->deprecated = $deprecated;
 
         if ($security === '') {
             //user wants to turn off security on this operation

src/Builders/Paths/Operation/ParametersBuilder.php

@@ -43,7 +43,7 @@ protected function buildPath(RouteInformation $route): Collection
                 }
 
                 /** @var Param $description */
-                $description = collect($route->actionDocBlock->getTagsByName('param'))
+                $description = collect($route->actionDocBlock?->getTagsByName('param'))
                     ->first(static fn (Param $param) => Str::snake($param->getVariableName()) === Str::snake($parameter['name']));
 
                 return Parameter::path()->name($parameter['name'])

src/Builders/Paths/OperationsBuilder.php

@@ -75,9 +75,9 @@ public function build(array|Collection $routes): array
             $operation = Operation::create()
                 ->action(Str::lower($operationAttribute->method) ?: $route->method)
                 ->tags(...$tags)
-                ->deprecated($this->isDeprecated($route->actionDocBlock))
-                ->description($route->actionDocBlock->getDescription()->render() !== '' ? $route->actionDocBlock->getDescription()->render() : null)
-                ->summary($route->actionDocBlock->getSummary() !== '' ? $route->actionDocBlock->getSummary() : null)
+                ->deprecated($operationAttribute->deprecated ?? $this->isDeprecated($route->actionDocBlock))
+                ->description($operationAttribute->description ?? ($route->actionDocBlock?->getDescription()->render() !== '' ? $route->actionDocBlock?->getDescription()->render() : null))
+                ->summary($operationAttribute->summary ?? ($route->actionDocBlock?->getSummary() !== '' ? $route->actionDocBlock?->getSummary() : null))
                 ->operationId($operationId)
                 ->parameters(...$parameters)
                 ->requestBody($requestBody)

tests/PetstoreTest.php

@@ -37,6 +37,7 @@ public function testGenerate(): void
 
         self::assertSame([
             'summary' => 'List all pets.',
+            'description' => 'List all pets from the database.',
             'operationId' => 'listPets',
             'parameters' => [
                 [
@@ -55,6 +56,7 @@ public function testGenerate(): void
                     '$ref' => '#/components/responses/ErrorValidation',
                 ],
             ],
+            'deprecated' => true,
         ], $spec['paths']['/pets']['get']);
 
         self::assertArrayHasKey('components', $spec);