fix(OpenApiType): Forbid using ambigous array syntaxes

Signed-off-by: provokateurin <[email protected]>
nextcloud · Sep 24, 2024 · f8c6811 · f8c6811
1 parent f91de91
commit f8c6811
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 47 deletions.
diff --git a/src/OpenApiType.php b/src/OpenApiType.php
@@ -174,13 +174,19 @@ public static function resolve(string $context, array $definitions, ParamTagValu
 		}
 
 		if ($node instanceof ArrayTypeNode) {
+			Logger::error($context, "The 'TYPE[]' syntax for arrays is forbidden due to ambiguities. Use 'list<TYPE>' for JSON arrays or 'array<string, TYPE>' for JSON objects instead.");
+
 			return new OpenApiType(
 				context: $context,
 				type: 'array',
 				items: self::resolve($context . ': items', $definitions, $node->type),
 			);
 		}
 		if ($node instanceof GenericTypeNode && ($node->type->name == 'array' || $node->type->name == 'list') && count($node->genericTypes) == 1) {
+			if ($node->type->name === 'array') {
+				Logger::error($context, "The 'array<TYPE>' syntax for arrays is forbidden due to ambiguities. Use 'list<TYPE>' for JSON arrays or 'array<string, TYPE>' for JSON objects instead.");
+			}
+
 			if ($node->genericTypes[0] instanceof IdentifierTypeNode && $node->genericTypes[0]->name == 'empty') {
 				return new OpenApiType(
 					context: $context,

diff --git a/tests/lib/Controller/AdminSettingsController.php b/tests/lib/Controller/AdminSettingsController.php
@@ -18,7 +18,7 @@ class AdminSettingsController extends OCSController {
 	/**
 	 * Route is only in the admin scope because there is no "NoAdminRequired" annotation or attribute
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */
@@ -29,7 +29,7 @@ public function adminScopeImplicitFromAdminRequired(): DataResponse {
 	/**
 	 * Route is in the default scope because the method overwrites with the Attribute
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */
@@ -41,7 +41,7 @@ public function movedToDefaultScope(): DataResponse {
 	/**
 	 * Route in default scope with tags
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */
@@ -53,7 +53,7 @@ public function movedToSettingsTag(): DataResponse {
 	/**
 	 * Route in default scope with tags but without named parameters on the attribute
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */

diff --git a/tests/lib/Controller/ExAppSettingsController.php b/tests/lib/Controller/ExAppSettingsController.php
@@ -20,7 +20,7 @@ class ExAppSettingsController extends OCSController {
 	/**
 	 * Route is in ex_app scope because of the attribute
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */
@@ -32,7 +32,7 @@ public function exAppScopeAttribute(): DataResponse {
 	/**
 	 * Route is in ex_app scope because of the override
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */

diff --git a/tests/lib/Controller/FederationController.php b/tests/lib/Controller/FederationController.php
@@ -29,7 +29,7 @@ class FederationController extends OCSController {
 	 *
 	 * Route is in federation scope as per controller scope
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: OK
 	 */
@@ -43,7 +43,7 @@ public function federationByController(): DataResponse {
 	 * Route is only in the default scope (moved from federation)
 	 *
 	 * @param NotificationsRequestProperty $property Property
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Personal settings updated
 	 */

diff --git a/tests/lib/Controller/RoutingController.php b/tests/lib/Controller/RoutingController.php
@@ -16,7 +16,7 @@
 class RoutingController extends OCSController {
 	/**
 	 * OCS Route with attribute
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Success
 	 */
@@ -30,7 +30,7 @@ public function attributeOCS() {
 	 * @NoCSRFRequired
 	 *
 	 * Index Route with attribute
-	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<empty>, array{}>
 	 *
 	 * 200: Success
 	 */