From 00e61c493277b7b1c7ab470a53fe4083f32abcc1 Mon Sep 17 00:00:00 2001
From: provokateurin <kate@provokateurin.de>
Date: Thu, 12 Mar 2026 15:38:44 +0100
Subject: [PATCH] feat: Warn about responses with lists without a limit
 parameter

Signed-off-by: provokateurin <kate@provokateurin.de>
---
 generate-spec.php | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/generate-spec.php b/generate-spec.php
index ebfa43e..38eae09 100755
--- a/generate-spec.php
+++ b/generate-spec.php
@@ -545,11 +545,14 @@
 			continue;
 		}
 
+		$hasLimitParameter = false;
 		foreach ($controllerMethod->parameters as $parameter) {
 			if ($parameter->name !== 'limit') {
 				continue;
 			}
 
+			$hasLimitParameter = true;
+
 			if ($parameter->type->type !== 'integer') {
 				Logger::debug($routeName . ': @param: ' . $parameter->name, 'Type was not an integer: ' . $parameter->type->type);
 				continue;
@@ -560,6 +563,19 @@
 			}
 		}
 
+		foreach ($controllerMethod->responses as $response) {
+			if ($response->type === null) {
+				continue;
+			}
+
+			// maxItems=0 is list<empty> which is just for the legacy [] empty response.
+			if ($response->type->type === 'array' && $response->type->maxItems !== 0 && !$hasLimitParameter) {
+				Logger::warning($routeName, 'The endpoint returns a list, but has no parameter to limit the number of items.');
+				// Only show the warning once, even if multiple responses contain lists.
+				break;
+			}
+		}
+
 		$operationId = [
 			$tagName,
 			...Helpers::splitOnUppercaseFollowedByNonUppercase($methodName)