From 9f6ef380395a69e1c98c002a2979d9cf4b21bf2d Mon Sep 17 00:00:00 2001
From: Diwak4r <diwak4r.comp@gmail.com>
Date: Sun, 26 Jul 2026 17:36:36 +0545
Subject: [PATCH] fix(openapi): handle non-numeric OpenAPI response keys in
 return-doc

sorted() used int(item[0]) as the sort key over the Responses Object,
which raised ValueError for valid non-numeric keys such as 'default' or
range codes ('2XX'). These are common in real specs, so loading any
OpenAPI toolset whose operation declares a 'default' response crashed.
Non-numeric keys are now ordered after numeric status codes.
---
 .../adk/tools/openapi_tool/common/common.py   |  8 ++++++--
 .../tools/openapi_tool/common/test_common.py  | 19 +++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/google/adk/tools/openapi_tool/common/common.py b/src/google/adk/tools/openapi_tool/common/common.py
index 3b9b6b2497d..26bf632ac7f 100644
--- a/src/google/adk/tools/openapi_tool/common/common.py
+++ b/src/google/adk/tools/openapi_tool/common/common.py
@@ -227,8 +227,12 @@ def generate_return_doc(responses: Dict[str, Response]) -> str:
 
     # Only consider 2xx responses for return type hinting.
     # Returns the 2xx response with the smallest status code number and with
-    # content defined.
-    sorted_responses = sorted(responses.items(), key=lambda item: int(item[0]))
+    # content defined. Non-numeric OpenAPI response keys (e.g. 'default' or
+    # range codes like '2XX') are valid and sorted after numeric status codes.
+    sorted_responses = sorted(
+        responses.items(),
+        key=lambda item: int(item[0]) if item[0].isdigit() else float('inf'),
+    )
     qualified_response = next(
         filter(
             lambda r: r[0].startswith('2') and r[1].content,
diff --git a/tests/unittests/tools/openapi_tool/common/test_common.py b/tests/unittests/tools/openapi_tool/common/test_common.py
index 1dd3195071f..37d1aac2261 100644
--- a/tests/unittests/tools/openapi_tool/common/test_common.py
+++ b/tests/unittests/tools/openapi_tool/common/test_common.py
@@ -392,6 +392,25 @@ def test_generate_return_doc_2xx_smallest_status_code_response(self):
         == expected_doc
     )
 
+  def test_generate_return_doc_non_numeric_status_keys(self):
+    # 'default' (and range codes like '2XX') are valid OpenAPI response keys
+    # and must not crash return-doc generation.
+    responses = {
+        '200': {
+            'description': 'Successful response',
+            'content': {'application/json': {'schema': {'type': 'string'}}},
+        },
+        'default': {
+            'description': 'Unexpected error',
+            'content': {'application/json': {'schema': {'type': 'object'}}},
+        },
+    }
+    expected_doc = 'Returns (str): Successful response'
+    assert (
+        PydocHelper.generate_return_doc(dict_to_responses(responses))
+        == expected_doc
+    )
+
   def test_generate_return_doc_contentful_response(self):
     responses = {
         '200': {'description': 'No content response'},