-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Description
Describe the bug
OpenAPI specification has path level parameters that defines the list of API parameters that commonly applies to all methods.
Ref: https://swagger.io/docs/specification/v3_0/describing-parameters/#common-parameters
The current implementation of OpenApiSpecParser._collect_operations() loads only method level parameters. Common parameters are discarded in the whole process.
To Reproduce
Steps to reproduce the behavior:
- Create a unittest for parsing an OpenAPI spec v3.0 with path-level parameters.
openapi_spec = { "openapi": "3.1.0", "info": {"title": "Combine Parameters API", "version": "1.0.0"}, "paths": { "/test": { "parameters": [ {"name": "global_param", "in": "query", "schema": {"type": "string"}} ], "get": { "parameters": [ {"name": "local_param", "in": "header", "schema": {"type": "integer"}} ], "operationId": "testGet", "responses": { "200": { "description": "Successful response", "content": { "application/json": {"schema": {"type": "string"}} }, } }, }, } }, } parsed_operations = openapi_spec_generator.parse(openapi_spec) assert len(parsed_operations) == 1 operation = parsed_operations[0] assert len(operation.parameters) == 2 # Verify the combined parameters global_param = next((p for p in operation.parameters if p.original_name == "global_param"), None) local_param = next((p for p in operation.parameters if p.original_name == "local_param"), None) assert global_param is not None assert global_param.param_location == "query" assert global_param.type_value is str assert local_param is not None assert local_param.param_location == "header" assert local_param.type_value is int
- Run this unittest
- See error

Expected behavior
In the unittest,
parsed_operations = openapi_spec_generator.parse(openapi_spec)
The returned parsed_operations should contains an operation with both local_param and global_param. The unittest should passed as shown below:

Root Cause Analysis
As shown in the current implementation, the _collect_operations method which loads parameters for every HTTP methods but the common parameters block at path level is skipped and not being processed in subsequent statements too.

Desktop (please complete the following information):
- OS: MacOS
- Python version(python -V): 3.13.3
- ADK version(pip show google-adk):
(adk-python) ➜ adk-python (fix/missing-path-level-parameters) pip show google-adk ✭ ✱
Name: google-adk
Version: 0.4.0
Summary: Agent Development Kit
Home-page: https://google.github.io/adk-docs/
Author:
Author-email: Google LLC <[email protected]>
License:
Location: /Users/kmak/Documents/Github/adk-python/.venv/lib/python3.13/site-packages
Requires: authlib, click, fastapi, google-api-python-client, google-cloud-aiplatform, google-cloud-secret-manager, google-cloud-speech, google-cloud-storage, google-genai, graphviz, mcp, opentelemetry-api, opentelemetry-exporter-gcp-trace, opentelemetry-sdk, pydantic, python-dotenv, PyYAML, sqlalchemy, tzlocal, uvicorn
Required-by:
Additional context
The problem was found while parsing the OpenAPI spec of Kubernetes API Server located in the following path:
https://raw.githubusercontent.com/kubernetes/kubernetes/refs/heads/master/api/openapi-spec/v3/api__v1_openapi.json