Skip to content

Commit 80e1020

Browse files
nickvergessennickvergessen
authored
Merge pull request #219 from nextcloud/bugfix/217/allow-deprecating-parameters
feat(deprecation): Allow deprecating parameters of controller methods
2 parents 3ef7c03 + f926c3e commit 80e1020

File tree

8 files changed

+1249
-2
lines changed

8 files changed

+1249
-2
lines changed

‎generate-spec.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -824,6 +824,9 @@
824824
if (!$queryParameter->type->nullable && !$queryParameter->type->hasDefaultValue) {
825825
$parameter['required'] = true;
826826
}
827+
if ($queryParameter->type->deprecated) {
828+
$parameter['deprecated'] = true;
829+
}
827830
$parameter['schema'] = $queryParameter->type->toArray(true);
828831

829832
$parameters[] = $parameter;

‎src/ControllerMethod.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,11 @@ public static function parse(string $context,
230230
continue;
231231
}
232232

233+
if (str_contains($param->type->description, '@deprecated')) {
234+
$param->type->deprecated = true;
235+
$param->type->description = str_replace('@deprecated', 'Deprecated:', $param->type->description);
236+
}
237+
233238
$parameters[] = $param;
234239
}
235240

‎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
@@ -42,6 +42,7 @@ public function __construct(
4242
public ?string $format = null,
4343
public bool $nullable = false,
4444
public bool $hasDefaultValue = false,
45+
public bool $deprecated = false,
4546
public mixed $defaultValue = null,
4647
public ?OpenApiType $items = null,
4748
public ?array $properties = null,
@@ -100,6 +101,9 @@ enum: [0, 1],
100101
if ($this->nullable) {
101102
$values['nullable'] = true;
102103
}
104+
if ($this->deprecated) {
105+
$values['deprecated'] = true;
106+
}
103107
if ($this->hasDefaultValue && $this->defaultValue !== null) {
104108
$values['default'] = $this->type === 'object' && empty($this->defaultValue) ? new stdClass() : $this->defaultValue;
105109
}

‎tests/appinfo/routes.php‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,5 +77,11 @@
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)']],
7979
['name' => 'Settings#docsParsingStatuscode', 'url' => '/api/{apiVersion}/docs-parsing-status-code', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
80+
['name' => 'Settings#deprecatedRoute', 'url' => '/api/{apiVersion}/deprecated', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
81+
['name' => 'Settings#deprecatedRouteGet', 'url' => '/api/{apiVersion}/deprecated-get', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(v2)']],
82+
['name' => 'Settings#deprecatedParameter', 'url' => '/api/{apiVersion}/deprecated-parameter', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
83+
['name' => 'Settings#deprecatedParameterGet', 'url' => '/api/{apiVersion}/deprecated-parameter-get', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(v2)']],
84+
['name' => 'Settings#deprecatedRouteAndParameter', 'url' => '/api/{apiVersion}/deprecated-route-parameter', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(v2)']],
85+
['name' => 'Settings#deprecatedRouteAndParameterGet', 'url' => '/api/{apiVersion}/deprecated-route-parameter-get', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(v2)']],
8086
],
8187
];

‎tests/lib/Controller/SettingsController.php‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -635,4 +635,84 @@ public function withCorsAttribute(): DataResponse {
635635
public function docsParsingStatuscode(string $param): DataResponse {
636636
return new DataResponse();
637637
}
638+
639+
/**
640+
* A deprecated POST route
641+
*
642+
* @param bool $active Not deprecated
643+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
644+
* @deprecated 1.0.0 Use {@see SettingsController::trueFalseParameter()} instead
645+
*
646+
* 200: Admin settings updated
647+
*/
648+
public function deprecatedRoute(bool $active): DataResponse {
649+
return new DataResponse();
650+
}
651+
652+
/**
653+
* A deprecated GET route
654+
*
655+
* @param bool $active Not deprecated
656+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
657+
* @deprecated 1.0.0 Use {@see SettingsController::trueFalseParameter()} instead
658+
*
659+
* 200: Admin settings updated
660+
*/
661+
public function deprecatedRouteGet(bool $active): DataResponse {
662+
return new DataResponse();
663+
}
664+
665+
/**
666+
* A deprecated parameter does not deprecate the POST method
667+
*
668+
* @param bool $active Not deprecated
669+
* @param bool $deprecated boolean @deprecated This parameter will be removed in a future version
670+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
671+
*
672+
* 200: Admin settings updated
673+
*/
674+
public function deprecatedParameter(bool $active, bool $deprecated): DataResponse {
675+
return new DataResponse();
676+
}
677+
678+
/**
679+
* A deprecated parameter does not deprecate the GET method
680+
*
681+
* @param bool $active Not deprecated
682+
* @param bool $deprecated boolean @deprecated This parameter will be removed in a future version
683+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
684+
*
685+
* 200: Admin settings updated
686+
*/
687+
public function deprecatedParameterGet(bool $active, bool $deprecated): DataResponse {
688+
return new DataResponse();
689+
}
690+
691+
/**
692+
* A deprecated parameter on a deprecated POST method
693+
*
694+
* @param bool $active Not deprecated
695+
* @param bool $deprecated boolean @deprecated This parameter will be removed in a future version
696+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
697+
* @deprecated 1.0.0 Use {@see SettingsController::trueFalseParameter()} instead
698+
*
699+
* 200: Admin settings updated
700+
*/
701+
public function deprecatedRouteAndParameter(bool $active, bool $deprecated): DataResponse {
702+
return new DataResponse();
703+
}
704+
705+
/**
706+
* A deprecated parameter on a deprecated GET method
707+
*
708+
* @param bool $active Not deprecated
709+
* @param bool $deprecated boolean @deprecated This parameter will be removed in a future version
710+
* @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
711+
* @deprecated 1.0.0 Use {@see SettingsController::trueFalseParameter()} instead
712+
*
713+
* 200: Admin settings updated
714+
*/
715+
public function deprecatedRouteAndParameterGet(bool $active, bool $deprecated): DataResponse {
716+
return new DataResponse();
717+
}
638718
}

0 commit comments

Comments
 (0)