fix(api): don't return list for runtime tools (#1686)

# What does this PR do?

Don't return list for runtime tools. Instead return Response object for
pagination and consistency with other APIs.

---------

Signed-off-by: Ihar Hrachyshka <ihar.hrachyshka@gmail.com>

docs/openapi_generator/pyopenapi/utility.py

@@ -132,7 +132,18 @@ def _validate_api_method_return_type(method) -> str | None:
 
     return_type = hints['return']
     if is_optional_type(return_type):
-        return "returns Optional type"
+        return "returns Optional type where a return value is mandatory"
+
+
+def _validate_api_method_doesnt_return_list(method) -> str | None:
+    hints = get_type_hints(method)
+
+    if 'return' not in hints:
+        return "has no return type annotation"
+
+    return_type = hints['return']
+    if get_origin(return_type) is list:
+        return "returns a list where a PaginatedResponse or List*Response object is expected"
 
 
 def _validate_api_delete_method_returns_none(method) -> str | None:
@@ -143,7 +154,7 @@ def _validate_api_delete_method_returns_none(method) -> str | None:
 
     return_type = hints['return']
     if return_type is not None and return_type is not type(None):
-        return "does not return None"
+        return "does not return None where None is mandatory"
 
 
 def _validate_list_parameters_contain_data(method) -> str | None:
@@ -160,13 +171,14 @@ def _validate_list_parameters_contain_data(method) -> str | None:
         return
 
     if 'data' not in return_type.model_fields:
-        return "does not have data attribute"
+        return "does not have a mandatory data attribute containing the list of objects"
 
 
 _VALIDATORS = {
     "GET": [
         _validate_api_method_return_type,
         _validate_list_parameters_contain_data,
+        _validate_api_method_doesnt_return_list,
     ],
     "DELETE": [
         _validate_api_delete_method_returns_none,