fix: rendering of openapi parameter examples (#2509)

Parameter examples should be a mapping of example names mapped to `Example` objects.

This PR builds such a mapping for parameters that have examples defined.

This PR does not modify existing behavior that adds examples to the parameter's schema object.

Closes #2494

litestar/_openapi/parameters.py

@@ -18,7 +18,7 @@
     from litestar._openapi.schema_generation import SchemaCreator
     from litestar.di import Provide
     from litestar.handlers.base import BaseRouteHandler
-    from litestar.openapi.spec import Reference
+    from litestar.openapi.spec import Example, Reference
     from litestar.types.internal_types import PathParameterDefinition
 
 
@@ -109,12 +109,17 @@ def create_parameter(
 
     schema = result if isinstance(result, Schema) else schema_creator.schemas[result.value]
 
+    examples: dict[str, Example | Reference] = {}
+    for i, example in enumerate(kwarg_definition.examples or [] if kwarg_definition else []):
+        examples[f"{field_definition.name}-example-{i}"] = example
+
     return Parameter(
         description=schema.description,
         name=parameter_name,
         param_in=param_in,
         required=is_required,
         schema=result,
+        examples=examples or None,
     )
 
 

tests/unit/test_openapi/test_parameters.py

@@ -1,6 +1,7 @@
 from typing import TYPE_CHECKING, List, Optional, Type, cast
 
 import pytest
+from typing_extensions import Annotated
 
 from litestar import Controller, Litestar, Router, get
 from litestar._openapi.parameters import create_parameter_for_handler
@@ -11,9 +12,11 @@
 from litestar.di import Provide
 from litestar.enums import ParamType
 from litestar.exceptions import ImproperlyConfiguredException
-from litestar.openapi.spec import OpenAPI
+from litestar.openapi import OpenAPIConfig
+from litestar.openapi.spec import Example, OpenAPI
 from litestar.openapi.spec.enums import OpenAPIType
 from litestar.params import Dependency, Parameter
+from litestar.testing import create_test_client
 from litestar.utils import find_index
 
 if TYPE_CHECKING:
@@ -306,3 +309,19 @@ def my_handler(
     assert local.schema.type == OpenAPIType.INTEGER  # type: ignore
     assert local.required
     assert local.schema.examples  # type: ignore
+
+
+def test_parameter_examples() -> None:
+    @get(path="/")
+    async def index(
+        text: Annotated[str, Parameter(examples=[Example(value="example value", summary="example summary")])]
+    ) -> str:
+        return text
+
+    with create_test_client(
+        route_handlers=[index], openapi_config=OpenAPIConfig(title="Test API", version="1.0.0")
+    ) as client:
+        response = client.get("/schema/openapi.json")
+        assert response.json()["paths"]["/"]["get"]["parameters"][0]["examples"] == {
+            "text-example-0": {"summary": "example summary", "value": "example value"}
+        }