fix(openapi): extract parameter-level example and examples (#4793)

fastmcp_slim/fastmcp/utilities/openapi/parser.py

@@ -318,6 +318,12 @@ class OpenAPIParser(
                         ):
                             param_schema_dict["default"] = resolved_media_schema.default
 
+                param_example = getattr(parameter, "example", None)
+                if param_example is not None:
+                    param_schema_dict.pop("example", None)
+                    param_schema_dict.pop("examples", None)
+                    param_schema_dict["example"] = param_example
+
                 # Extract explode and style properties if present
                 explode = getattr(parameter, "explode", None)
                 style = getattr(parameter, "style", None)

tests/utilities/openapi/test_parser.py

@@ -3,6 +3,7 @@
 import pytest
 
 from fastmcp.utilities.openapi.parser import parse_openapi_to_http_routes
+from fastmcp.utilities.openapi.schemas import _combine_schemas_and_map_params
 
 
 class TestOpenAPIParser:
@@ -458,3 +459,68 @@ class TestErrorHandling:
         routes = parse_openapi_to_http_routes(spec_with_broken_ref)
         # May have empty routes or skip the broken operation
         assert isinstance(routes, list)
+
+
+class TestParameterExamples:
+    """Test singular parameter-level example propagation."""
+
+    def test_parameter_example_propagation(self):
+        """Test singular parameter example propagation, default preservation, and overriding schema-level examples."""
+        spec = {
+            "openapi": "3.1.0",
+            "info": {"title": "Parameter Example Test", "version": "1.0.0"},
+            "paths": {
+                "/test": {
+                    "get": {
+                        "operationId": "test_op",
+                        "parameters": [
+                            {
+                                "name": "startYearMonth",
+                                "in": "query",
+                                "required": True,
+                                "example": "201601",
+                                "schema": {"type": "string"},
+                            },
+                            {
+                                "name": "pageNo",
+                                "in": "query",
+                                "example": 3,
+                                "schema": {"type": "integer", "default": 1},
+                            },
+                            {
+                                "name": "overrideSchemaExamples",
+                                "in": "query",
+                                "example": "PARAM_EXAMPLE",
+                                "schema": {
+                                    "type": "string",
+                                    "example": "SCHEMA_EXAMPLE",
+                                    "examples": [
+                                        "SCHEMA_EXAMPLES_1",
+                                        "SCHEMA_EXAMPLES_2",
+                                    ],
+                                },
+                            },
+                        ],
+                        "responses": {"200": {"description": "OK"}},
+                    }
+                }
+            },
+        }
+
+        routes = parse_openapi_to_http_routes(spec)
+        assert len(routes) == 1
+        route = routes[0]
+
+        schema, _ = _combine_schemas_and_map_params(route)
+        props = schema["properties"]
+
+        # 1. Singular parameter example propagated
+        assert props["startYearMonth"]["example"] == "201601"
+
+        # 2. Parameter example propagated and schema default preserved
+        assert props["pageNo"]["example"] == 3
+        assert props["pageNo"]["default"] == 1
+
+        # 3. Parameter-level example overrides schema-level example and examples
+        assert props["overrideSchemaExamples"]["example"] == "PARAM_EXAMPLE"
+        assert "examples" not in props["overrideSchemaExamples"]