feat: add deprecation support for QueryParam and BodyParam (#1022)

s-shiryaev · web-flow · commit 0b578d17c8be · 2025-10-21T00:22:16.000+02:00
* QueryParams and BodyParams can be marked as deprecated

* Add support for marking OpenAPI parameters as deprecated
diff --git a/camel/Extraction/Parameter.php b/camel/Extraction/Parameter.php
@@ -15,6 +15,7 @@ class Parameter extends BaseDTO
     public array $enumValues = [];
     public bool $exampleWasSpecified = false;
     public bool $nullable = false;
+    public bool $deprecated = false;
 
     public function __construct(array $parameters = [])
     {
diff --git a/resources/views/components/field-details.blade.php b/resources/views/components/field-details.blade.php
@@ -4,6 +4,7 @@
 <b style="line-height: 2;"><code>{{ $name }}</code></b>&nbsp;&nbsp;
 @if($type)<small>{{ $type }}</small>@endif&nbsp;
 @if($isInput && !$required)<i>optional</i>@endif &nbsp;
+@if($isInput && $deprecated)<i>deprecated</i>@endif &nbsp;
 @if($isInput && empty($hasChildren))
     @php
         $isList = Str::endsWith($type, '[]');
diff --git a/resources/views/components/nested-fields.blade.php b/resources/views/components/nested-fields.blade.php
@@ -23,6 +23,7 @@
                           'fullName' => $subfield['name'],
                           'type' => $subfield['type'] ?? 'string',
                           'required' => $subfield['required'] ?? false,
+                          'deprecated' => $subfield['deprecated'] ?? false,
                           'description' => $subfield['description'] ?? '',
                           'example' => $subfield['example'] ?? '',
                           'enumValues' => $subfield['enumValues'] ?? null,
@@ -44,6 +45,7 @@
                   'fullName' => $field['name'],
                   'type' => $field['type'] ?? 'string',
                   'required' => $field['required'] ?? false,
+                  'deprecated' => $field['deprecated'] ?? false,
                   'description' => $field['description'] ?? '',
                   'example' => $field['example'] ?? '',
                   'enumValues' => $field['enumValues'] ?? null,
@@ -66,6 +68,7 @@
                           'fullName' => $subfield['name'],
                           'type' => $subfield['type'] ?? 'string',
                           'required' => $subfield['required'] ?? false,
+                          'deprecated' => $subfield['deprecated'] ?? false,
                           'description' => $subfield['description'] ?? '',
                           'example' => $subfield['example'] ?? '',
                           'enumValues' => $subfield['enumValues'] ?? null,
@@ -87,6 +90,7 @@
               'fullName' => $field['name'],
               'type' => $field['type'] ?? 'string',
               'required' => $field['required'] ?? false,
+              'deprecated' => $field['deprecated'] ?? false,
               'description' => $field['description'] ?? '',
               'example' => $field['example'] ?? '',
               'enumValues' => $field['enumValues'] ?? null,
diff --git a/resources/views/themes/default/endpoint.blade.php b/resources/views/themes/default/endpoint.blade.php
@@ -113,6 +113,7 @@
                   'name' => $name,
                   'type' => null,
                   'required' => true,
+                  'deprecated' => false,
                   'description' => null,
                   'example' => $example,
                   'endpointId' => $endpoint->endpointId(),
@@ -132,6 +133,7 @@
                   'name' => $parameter->name,
                   'type' => $parameter->type ?? 'string',
                   'required' => $parameter->required,
+                  'deprecated' => $parameter->deprecated,
                   'description' => $parameter->description,
                   'example' => $parameter->example ?? '',
                   'enumValues' => $parameter->enumValues,
@@ -157,6 +159,7 @@
                   'name' => $parameter->name,
                   'type' => $parameter->type,
                   'required' => $parameter->required,
+                  'deprecated' => $parameter->deprecated,
                   'description' => $parameter->description,
                   'example' => $parameter->example ?? '',
                   'enumValues' => $parameter->enumValues,
diff --git a/resources/views/themes/elements/components/field-details.blade.php b/resources/views/themes/elements/components/field-details.blade.php
@@ -25,10 +25,17 @@ class="svg-inline--fa fa-chevron-right fa-fw fa-sm sl-icon" role="img"
                         <span class="sl-truncate sl-text-muted">{{ $type }}</span>
                     @endif
                 </div>
-                @if($required)
-                    <div class="sl-flex-1 sl-h-px sl-mx-3"></div>
-                    <span class="sl-ml-2 sl-text-warning">required</span>
-                @endif
+                    @if($required || $deprecated)
+                        <div class="sl-flex-1 sl-h-px sl-mx-3"></div>
+                        <div class="sl-flex sl-items-center">
+                            @if($required)
+                                <span class="sl-ml-2 sl-text-warning">required</span>
+                            @endif
+                            @if($deprecated)
+                                <span class="sl-ml-2 sl-text-warning">deprecated</span>
+                            @endif
+                        </div>
+                    @endif
             @endunless
         </div>
         @if($description)
diff --git a/resources/views/themes/elements/components/nested-fields.blade.php b/resources/views/themes/elements/components/nested-fields.blade.php
@@ -13,6 +13,7 @@
           'name' => $name,
           'type' => $field['type'] ?? 'string',
           'required' => $field['required'] ?? false,
+          'deprecated' => $field['deprecated'] ?? false,
           'description' => $field['description'] ?? '',
           'example' => $field['example'] ?? '',
           'enumValues' => $field['enumValues'] ?? null,
diff --git a/resources/views/themes/elements/endpoint.blade.php b/resources/views/themes/elements/endpoint.blade.php
@@ -69,6 +69,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{!! rtrim($baseUrl, '/')
                                       'name' => $header,
                                       'type' => null,
                                       'required' => false,
+                                      'deprecated' => false,
                                       'description' => null,
                                       'example' => $value,
                                       'endpointId' => $endpoint->endpointId(),
@@ -91,6 +92,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{!! rtrim($baseUrl, '/')
                                       'name' => $parameter->name,
                                       'type' => $parameter->type ?? 'string',
                                       'required' => $parameter->required,
+                                      'deprecated' => $parameter->deprecated,
                                       'description' => $parameter->description,
                                       'example' => $parameter->example ?? '',
                                       'enumValues' => $parameter->enumValues,
@@ -115,6 +117,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{!! rtrim($baseUrl, '/')
                                           'name' => $parameter->name,
                                           'type' => $parameter->type,
                                           'required' => $parameter->required,
+                                          'deprecated' => $parameter->deprecated,
                                           'description' => $parameter->description,
                                           'example' => $parameter->example ?? '',
                                           'enumValues' => $parameter->enumValues,
diff --git a/src/Attributes/GenericParam.php b/src/Attributes/GenericParam.php
@@ -15,6 +15,7 @@ public function __construct(
         public mixed $example = null, /* Pass 'No-example' to omit the example */
         public mixed $enum = null, // Can pass a list of values, or a native PHP enum
         public ?bool $nullable = false,
+        public ?bool $deprecated = false,
     ) {
     }
 
@@ -28,6 +29,7 @@ public function toArray()
             "example" => $this->example,
             "enumValues" => $this->getEnumValues(),
             'nullable' => $this->nullable,
+            'deprecated' => $this->deprecated,
         ];
     }
 
diff --git a/src/Attributes/ResponseField.php b/src/Attributes/ResponseField.php
@@ -17,6 +17,7 @@ public function __construct(
         public mixed $example = null, /* Pass 'No-example' to omit the example */
         public mixed $enum = null, // Can pass a list of values, or a native PHP enum,
         public ?bool $nullable = false,
+        public ?bool $deprecated = false,
     ) {
     }
 }
diff --git a/src/Extracting/Strategies/BodyParameters/GetFromBodyParamTag.php b/src/Extracting/Strategies/BodyParameters/GetFromBodyParamTag.php
@@ -11,31 +11,37 @@ class GetFromBodyParamTag extends GetFieldsFromTagStrategy
     public function parseTag(string $tagContent): array
     {
         // Format:
-        // @bodyParam <name> <type> <"required" (optional)> <description>
+        // @bodyParam <name> <type> <"required" (optional)> <"deprecated" (optional)> <description>
         // Examples:
         // @bodyParam text string required The text.
         // @bodyParam user_id integer The ID of the user.
-        preg_match('/(.+?)\s+(.+?)\s+(required\s+)?([\s\S]*)/', $tagContent, $parsedContent);
+        // @bodyParam status string required deprecated Use `is_active` instead.
+        preg_match('/(.+?)\s+(.+?)\s+(required\s+)?(deprecated\s+)?([\s\S]*)/', $tagContent, $parsedContent);
 
         if (empty($parsedContent)) {
             // This means only name and type were supplied
             [$name, $type] = preg_split('/\s+/', $tagContent);
             $required = false;
+            $deprecated = false;
             $description = '';
         } else {
-            [$_, $name, $type, $required, $description] = $parsedContent;
+            [$_, $name, $type, $required, $deprecated, $description] = $parsedContent;
             $description = trim(str_replace(['No-example.', 'No-example'], '', $description));
             if ($description == 'required') {
                 $required = $description;
                 $description = '';
+            } elseif ($description == 'deprecated') {
+                $deprecated = $description;
+                $description = '';
             }
             $required = trim($required) === 'required';
+            $deprecated = trim($deprecated) === 'deprecated';
         }
 
         $type = static::normalizeTypeName($type);
         [$description, $example, $enumValues, $exampleWasSpecified] =
             $this->getDescriptionAndExample($description, $type, $tagContent, $name);
 
-        return compact('name', 'type', 'description', 'required', 'example', 'enumValues', 'exampleWasSpecified');
+        return compact('name', 'type', 'description', 'required', 'deprecated', 'example', 'enumValues', 'exampleWasSpecified');
     }
 }
diff --git a/src/Extracting/Strategies/QueryParameters/GetFromQueryParamTag.php b/src/Extracting/Strategies/QueryParameters/GetFromQueryParamTag.php
@@ -12,28 +12,34 @@ class GetFromQueryParamTag extends GetFieldsFromTagStrategy
     public function parseTag(string $tagContent): array
     {
         // Format:
-        // @queryParam <name> <type (optional)> <"required" (optional)> <description>
+        // @queryParam <name> <type (optional)> <"required" (optional)> <"deprecated" (optional)> <description>
         // Examples:
         // @queryParam text required The text.
         // @queryParam user_id integer The ID of the user.
-        preg_match('/(.+?)\s+([a-zA-Z\[\]]+\s+)?(required\s+)?([\s\S]*)/', $tagContent, $content);
+        // @queryParam sort string deprecated Use `order` parameter instead.
+        preg_match('/(.+?)\s+([a-zA-Z\[\]]+\s+)?(required\s+)?(deprecated\s+)?([\s\S]*)/', $tagContent, $content);
 
         if (empty($content)) {
             // This means only name was supplied
             $name = $tagContent;
             $required = false;
+            $deprecated = false;
             $description = '';
             $type = 'string';
         } else {
-            [$_, $name, $type, $required, $description] = $content;
+            [$_, $name, $type, $required, $deprecated, $description] = $content;
 
             $description = trim(str_replace(['No-example.', 'No-example'], '', $description));
             if ($description === 'required') {
                 // No description was supplied
                 $required = true;
                 $description = '';
+            } elseif ($description === 'deprecated') {
+                $deprecated = true;
+                $description = '';
             } else {
                 $required = trim($required) === 'required';
+                $deprecated = trim($deprecated) === 'deprecated';
             }
 
             $type = trim($type);
@@ -42,6 +48,10 @@ public function parseTag(string $tagContent): array
                     // Type wasn't supplied
                     $type = 'string';
                     $required = true;
+                } elseif ($type === 'deprecated') {
+                    // Type wasn't supplied but deprecated was
+                    $type = 'string';
+                    $deprecated = true;
                 } else {
                     $type = static::normalizeTypeName($type);
                     // Type in annotation is optional
@@ -66,6 +76,6 @@ public function parseTag(string $tagContent): array
         [$description, $example, $enumValues, $exampleWasSpecified] =
             $this->getDescriptionAndExample($description, $type, $tagContent, $name);
 
-        return compact('name', 'description', 'required', 'example', 'type', 'enumValues', 'exampleWasSpecified');
+        return compact('name', 'description', 'required', 'deprecated', 'example', 'type', 'enumValues', 'exampleWasSpecified');
     }
 }
diff --git a/src/Writing/OpenApiSpecGenerators/BaseGenerator.php b/src/Writing/OpenApiSpecGenerators/BaseGenerator.php
@@ -138,6 +138,9 @@ protected function generateEndpointParametersSpec(OutputEndpointData $endpoint):
                     'required' => $details->required,
                     'schema' => $this->generateFieldData($details),
                 ];
+                if ($details->deprecated) {
+                    $parameterData['deprecated'] = true;
+                }
                 $parameters[] = $parameterData;
             }
         }
@@ -196,6 +199,9 @@ protected function generateEndpointRequestBodySpec(OutputEndpointData $endpoint)
                 }
 
                 $fieldData = $this->generateFieldData($details);
+                if ($details['deprecated']) {
+                    $fieldData['deprecated'] = true;
+                }
 
                 $schema['properties'][$name] = $fieldData;
             }
diff --git a/tests/GenerateDocumentation/OutputTest.php b/tests/GenerateDocumentation/OutputTest.php
@@ -450,6 +450,7 @@ public function will_not_overwrite_manually_modified_content_unless_force_flag_i
             'custom' => [],
             'exampleWasSpecified' => false,
             'nullable' => false,
+            'deprecated' => false,
         ];
         $group['endpoints'][0]['urlParameters']['a_param'] = $extraParam;
         file_put_contents($firstGroupFilePath, Yaml::dump(
diff --git a/tests/Strategies/BodyParameters/GetFromBodyParamAttributeTest.php b/tests/Strategies/BodyParameters/GetFromBodyParamAttributeTest.php
@@ -71,6 +71,37 @@ public function can_fetch_from_bodyparam_attribute()
                 'required' => false,
                 'nullable' => false,
             ],
+            'book_id' => [
+                'type' => 'string',
+                'description' => 'Book ID',
+                'required' => true,
+                'deprecated' => true,
+            ],
+            'team_id' => [
+                'type' => 'string',
+                'description' => 'Team ID',
+                'required' => true,
+                'deprecated' => true,
+            ],
+            'device' => [
+                'type' => 'object',
+                'description' => 'Device',
+                'required' => false,
+                'deprecated' => true,
+            ],
+            'devices' => [
+                'type' => 'string[]',
+                'description' => '',
+                'required' => true,
+                'deprecated' => true,
+            ],
+            'teams' => [
+                'type' => 'string[]',
+                'description' => 'Teams',
+                'required' => true,
+                'deprecated' => true,
+                'example' => ['1', '2']
+            ],
             'book' => [
                 'type' => 'object',
                 'description' => 'Book information',
@@ -248,6 +279,11 @@ class BodyParamAttributeTestController
     #[BodyParam("yet_another_param.name", "string")]
     #[BodyParam("even_more_param", "number[]", "A list of numbers", required: false)]
     #[BodyParam("book", "object", "Book information", required: false)]
+    #[BodyParam("book_id", "string", "Book ID", required: true, deprecated: true)]
+    #[BodyParam("team_id", "string", "Team ID", required: true, deprecated: true)]
+    #[BodyParam("teams", "string[]", "Teams", example: ["1", "2"], deprecated: true)]
+    #[BodyParam("device", "object", "Device", required: false, deprecated: true)]
+    #[BodyParam("devices", "string[]", deprecated: true)]
     #[BodyParam("book.name", type: "string")]
     #[BodyParam("book.author_id", type: "integer")]
     #[BodyParam("book.pages_count", type: "integer")]
diff --git a/tests/Strategies/BodyParameters/GetFromBodyParamTagTest.php b/tests/Strategies/BodyParameters/GetFromBodyParamTagTest.php
@@ -32,6 +32,11 @@ public function can_fetch_from_bodyparam_tag()
             new Tag('bodyParam', 'yet_another_param object required Some object params.'),
             new Tag('bodyParam', 'yet_another_param.name string required'),
             new Tag('bodyParam', 'even_more_param number[] A list of numbers'),
+            new Tag('bodyParam', 'book_id string required deprecated Book ID'),
+            new Tag('bodyParam', 'team_id string deprecated Team ID'),
+            new Tag('bodyParam', 'teams array deprecated Teams Example: ["1", "2"]'),
+            new Tag('bodyParam', 'device object deprecated Device'),
+            new Tag('bodyParam', 'devices array deprecated'),
             new Tag('bodyParam', 'book object Book information'),
             new Tag('bodyParam', 'book.name string'),
             new Tag('bodyParam', 'book.author_id integer'),
@@ -49,6 +54,7 @@ public function can_fetch_from_bodyparam_tag()
                 'required' => true,
                 'description' => 'The id of the user.',
                 'example' => 9,
+                'deprecated' => false,
             ],
             'room_id' => [
                 'type' => 'string',
@@ -81,6 +87,37 @@ public function can_fetch_from_bodyparam_tag()
                 'description' => 'A list of numbers',
                 'required' => false,
             ],
+            'book_id' => [
+                'type' => 'string',
+                'description' => 'Book ID',
+                'required' => true,
+                'deprecated' => true,
+            ],
+            'team_id' => [
+                'type' => 'string',
+                'description' => 'Team ID',
+                'required' => false,
+                'deprecated' => true,
+            ],
+            'device' => [
+                'type' => 'object',
+                'description' => 'Device',
+                'required' => false,
+                'deprecated' => true,
+            ],
+            'devices' => [
+                'type' => 'string[]',
+                'description' => '',
+                'required' => false,
+                'deprecated' => true,
+            ],
+            'teams' => [
+                'type' => 'string[]',
+                'description' => 'Teams',
+                'required' => false,
+                'deprecated' => true,
+                'example' => ['1', '2']
+            ],
             'book' => [
                 'type' => 'object',
                 'description' => 'Book information',
diff --git a/tests/Strategies/QueryParameters/GetFromQueryParamAttributeTest.php b/tests/Strategies/QueryParameters/GetFromQueryParamAttributeTest.php
diff --git a/tests/Strategies/QueryParameters/GetFromQueryParamTagTest.php b/tests/Strategies/QueryParameters/GetFromQueryParamTagTest.php
diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php

Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ class Parameter extends BaseDTO`
`15`	`15`	`public array $enumValues = [];`
`16`	`16`	`public bool $exampleWasSpecified = false;`
`17`	`17`	`public bool $nullable = false;`
	`18`	`+ public bool $deprecated = false;`
`18`	`19`
`19`	`20`	`public function __construct(array $parameters = [])`
`20`	`21`	`{`
Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ public function __construct(`
`15`	`15`	`public mixed $example = null, /* Pass 'No-example' to omit the example */`
`16`	`16`	`public mixed $enum = null, // Can pass a list of values, or a native PHP enum`
`17`	`17`	`public ?bool $nullable = false,`
	`18`	`+ public ?bool $deprecated = false,`
`18`	`19`	`) {`
`19`	`20`	`}`
`20`	`21`
`@@ -28,6 +29,7 @@ public function toArray()`
`28`	`29`	`"example" => $this->example,`
`29`	`30`	`"enumValues" => $this->getEnumValues(),`
`30`	`31`	`'nullable' => $this->nullable,`
	`32`	`+ 'deprecated' => $this->deprecated,`
`31`	`33`	`];`
`32`	`34`	`}`
`33`	`35`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ public function __construct(`
`17`	`17`	`public mixed $example = null, /* Pass 'No-example' to omit the example */`
`18`	`18`	`public mixed $enum = null, // Can pass a list of values, or a native PHP enum,`
`19`	`19`	`public ?bool $nullable = false,`
	`20`	`+ public ?bool $deprecated = false,`
`20`	`21`	`) {`
`21`	`22`	`}`
`22`	`23`	`}`