Skip to content

Commit 2f26338

Browse files
nickvergessennickvergessen
committed
feat(deprecation): Allow deprecating parameters of controller methods
Signed-off-by: Joas Schilling <[email protected]>
1 parent 6292e66 commit 2f26338

File tree

7 files changed

+410
-2
lines changed

7 files changed

+410
-2
lines changed

‎src/ControllerMethod.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,10 @@ public static function parse(string $context,
202202
continue;
203203
}
204204

205+
if (str_contains($param->type->description, '@deprecated')) {
206+
$param->type->deprecated = true;
207+
}
208+
205209
$parameters[] = $param;
206210
}
207211

‎src/Helpers.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,8 +150,13 @@ public static function cleanEmptyResponseArray(array $schema): array|stdClass {
150150

151151
public static function classMethodHasAnnotationOrAttribute(ClassMethod|Class_|Node $node, string $annotation): bool {
152152
$doc = $node->getDocComment()?->getText();
153-
if ($doc !== null && str_contains($doc, '@' . $annotation)) {
154-
return true;
153+
154+
if ($doc !== null) {
155+
if ($annotation !== 'deprecated' && str_contains($doc, '@' . $annotation)) {
156+
return true;
157+
} elseif ($annotation === 'deprecated' && str_contains($doc, '* @' . $annotation)) {
158+
return true;
159+
}
155160
}
156161

157162
/** @var AttributeGroup $attrGroup */

‎src/OpenApiType.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ public function __construct(
4040
public ?string $format = null,
4141
public bool $nullable = false,
4242
public bool $hasDefaultValue = false,
43+
public bool $deprecated = false,
4344
public mixed $defaultValue = null,
4445
public ?OpenApiType $items = null,
4546
public ?array $properties = null,
@@ -98,6 +99,9 @@ enum: [0, 1],
9899
if ($this->nullable) {
99100
$values['nullable'] = true;
100101
}
102+
if ($this->deprecated) {
103+
$values['deprecated'] = true;
104+
}
101105
if ($this->hasDefaultValue && $this->defaultValue !== null) {
102106
$values['default'] = $this->type === 'object' && empty($this->defaultValue) ? new stdClass() : $this->defaultValue;
103107
}

‎tests/appinfo/routes.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,5 +76,7 @@
7676
['name' => 'Settings#whitespace', 'url' => '/api/{apiVersion}/whitespace', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
7777
['name' => 'Settings#withCorsAnnotation', 'url' => '/api/{apiVersion}/cors/annotation', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
7878
['name' => 'Settings#withCorsAttribute', 'url' => '/api/{apiVersion}/cors/attribute', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
79+
['name' => 'Settings#deprecatedRoute', 'url' => '/api/{apiVersion}/deprecated', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
80+
['name' => 'Settings#deprecatedParameter', 'url' => '/api/{apiVersion}/deprecated-parameter', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
7981
],
8082
];

‎tests/lib/Controller/SettingsController.php‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -596,4 +596,29 @@ public function withCorsAnnotation(): DataResponse {
596596
public function withCorsAttribute(): DataResponse {
597597
return new DataResponse();
598598
}
599+
600+
/**
601+
* A deprecated route
602+
*
603+
* @param bool|true $yesOrNo boolean or true This parameter will be removed in a future version
604+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
605+
* @deprecated 1.0.0 Use {@see SettingsController::trueFalseParameter()} instead
606+
*
607+
* 200: Admin settings updated
608+
*/
609+
public function deprecatedRoute(bool $yesOrNo): DataResponse {
610+
return new DataResponse();
611+
}
612+
613+
/**
614+
* A deprecated parameter does not deprecate the method
615+
*
616+
* @param bool|true $yesOrNo boolean or true @deprecated This parameter will be removed in a future version
617+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
618+
*
619+
* 200: Admin settings updated
620+
*/
621+
public function deprecatedParameter(bool $yesOrNo): DataResponse {
622+
return new DataResponse();
623+
}
599624
}

‎tests/openapi-administration.json‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4638,6 +4638,190 @@
46384638
}
46394639
}
46404640
},
4641+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/deprecated": {
4642+
"post": {
4643+
"operationId": "settings-deprecated-route",
4644+
"summary": "A deprecated route",
4645+
"description": "This endpoint requires admin access",
4646+
"deprecated": true,
4647+
"tags": [
4648+
"settings"
4649+
],
4650+
"security": [
4651+
{
4652+
"bearer_auth": []
4653+
},
4654+
{
4655+
"basic_auth": []
4656+
}
4657+
],
4658+
"requestBody": {
4659+
"required": true,
4660+
"content": {
4661+
"application/json": {
4662+
"schema": {
4663+
"type": "object",
4664+
"required": [
4665+
"yesOrNo"
4666+
],
4667+
"properties": {
4668+
"yesOrNo": {
4669+
"type": "boolean",
4670+
"description": "boolean or true This parameter will be removed in a future version"
4671+
}
4672+
}
4673+
}
4674+
}
4675+
}
4676+
},
4677+
"parameters": [
4678+
{
4679+
"name": "apiVersion",
4680+
"in": "path",
4681+
"required": true,
4682+
"schema": {
4683+
"type": "string",
4684+
"enum": [
4685+
"v2"
4686+
],
4687+
"default": "v2"
4688+
}
4689+
},
4690+
{
4691+
"name": "OCS-APIRequest",
4692+
"in": "header",
4693+
"description": "Required to be true for the API request to pass",
4694+
"required": true,
4695+
"schema": {
4696+
"type": "boolean",
4697+
"default": true
4698+
}
4699+
}
4700+
],
4701+
"responses": {
4702+
"200": {
4703+
"description": "Admin settings updated",
4704+
"content": {
4705+
"application/json": {
4706+
"schema": {
4707+
"type": "object",
4708+
"required": [
4709+
"ocs"
4710+
],
4711+
"properties": {
4712+
"ocs": {
4713+
"type": "object",
4714+
"required": [
4715+
"meta",
4716+
"data"
4717+
],
4718+
"properties": {
4719+
"meta": {
4720+
"$ref": "#/components/schemas/OCSMeta"
4721+
},
4722+
"data": {}
4723+
}
4724+
}
4725+
}
4726+
}
4727+
}
4728+
}
4729+
}
4730+
}
4731+
}
4732+
},
4733+
"/ocs/v2.php/apps/notifications/api/{apiVersion}/deprecated-parameter": {
4734+
"post": {
4735+
"operationId": "settings-deprecated-parameter",
4736+
"summary": "A deprecated parameter does not deprecate the method",
4737+
"description": "This endpoint requires admin access",
4738+
"tags": [
4739+
"settings"
4740+
],
4741+
"security": [
4742+
{
4743+
"bearer_auth": []
4744+
},
4745+
{
4746+
"basic_auth": []
4747+
}
4748+
],
4749+
"requestBody": {
4750+
"required": true,
4751+
"content": {
4752+
"application/json": {
4753+
"schema": {
4754+
"type": "object",
4755+
"required": [
4756+
"yesOrNo"
4757+
],
4758+
"properties": {
4759+
"yesOrNo": {
4760+
"type": "boolean",
4761+
"deprecated": true,
4762+
"description": "boolean or true @deprecated This parameter will be removed in a future version"
4763+
}
4764+
}
4765+
}
4766+
}
4767+
}
4768+
},
4769+
"parameters": [
4770+
{
4771+
"name": "apiVersion",
4772+
"in": "path",
4773+
"required": true,
4774+
"schema": {
4775+
"type": "string",
4776+
"enum": [
4777+
"v2"
4778+
],
4779+
"default": "v2"
4780+
}
4781+
},
4782+
{
4783+
"name": "OCS-APIRequest",
4784+
"in": "header",
4785+
"description": "Required to be true for the API request to pass",
4786+
"required": true,
4787+
"schema": {
4788+
"type": "boolean",
4789+
"default": true
4790+
}
4791+
}
4792+
],
4793+
"responses": {
4794+
"200": {
4795+
"description": "Admin settings updated",
4796+
"content": {
4797+
"application/json": {
4798+
"schema": {
4799+
"type": "object",
4800+
"required": [
4801+
"ocs"
4802+
],
4803+
"properties": {
4804+
"ocs": {
4805+
"type": "object",
4806+
"required": [
4807+
"meta",
4808+
"data"
4809+
],
4810+
"properties": {
4811+
"meta": {
4812+
"$ref": "#/components/schemas/OCSMeta"
4813+
},
4814+
"data": {}
4815+
}
4816+
}
4817+
}
4818+
}
4819+
}
4820+
}
4821+
}
4822+
}
4823+
}
4824+
},
46414825
"/ocs/v2.php/tests/attribute-ocs/{param}": {
46424826
"get": {
46434827
"operationId": "routing-attributeocs-route",

0 commit comments

Comments
 (0)