We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
Bug: Wrong OpenAPI `examples` format and nesting
### Description

For examples to show up on SwaggerUI, the `examples` array should be an object and nested on the same level as `schema`, not under it.

Wrong definition:
```json
{
  "parameters": [
    {
      "schema": {
        "type": "string",
        "examples": [
          {
            "summary": "example summary",
            "value": "example value"
          }
        ]
      }
    }
  ]
}
````

Correct definition:
```json
{
  "parameters": [
    {
      "schema": {
        "type": "string"
      },
	  "examples": {
        "example1": {
          "summary": "example summary"
          "value": "example value"
        }
      }
    }
  ]
}
```

### MCVE

```python
from litestar import Litestar, get
from litestar.openapi import OpenAPIConfig
from litestar.openapi.spec.example import Example
from litestar.params import Parameter

from typing import Annotated


@get(path="/")
async def index(
    text: Annotated[
        str,
        Parameter(
            examples=[Example(value="example value", summary="example summary")]
        )
    ]
) -> str:
    return text

app = Litestar(
    route_handlers=[
        index
    ],
    openapi_config=OpenAPIConfig(
        title="Test API",
        version="1.0.0"
    )
)
```


### Steps to reproduce

```bash
1. Go to the SwaggerUI docs.
2. Click on the `index` GET method.
3. See that there are no examples under the `text` query parameter.
```


### Screenshots

![SwaggerUI query](https://github.com/litestar-org/litestar/assets/24798198/37dadcf0-7d5b-49c3-91e6-01c3bdd4137c)

### Litestar Version

2.1.1

### Platform

- [ ] Linux
- [ ] Mac
- [X] Windows
- [ ] Other (Please specify in the description above)

<!-- POLAR PLEDGE BADGE START -->
---
> [!NOTE]  
> While we are open for sponsoring on [GitHub Sponsors](https://github.com/sponsors/litestar-org/) and 
> [OpenCollective](https://opencollective.com/litestar), we also utilize [Polar.sh](https://polar.sh/) to engage in pledge-based sponsorship.
>
> Check out all issues funded or available for funding [on our Polar.sh Litestar dashboard](https://polar.sh/litestar-org)
> * If you would like to see an issue prioritized, make a pledge towards it!
> * We receive the pledge once the issue is completed & verified
> * This, along with engagement in the community, helps us know which features are a priority to our users.

<a href="https://polar.sh/litestar-org/litestar/issues/2494">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://polar.sh/api/github/litestar-org/litestar/issues/2494/pledge.svg?darkmode=1">
  <img alt="Fund with Polar" src="https://polar.sh/api/github/litestar-org/litestar/issues/2494/pledge.svg">
</picture>
</a>
<!-- POLAR PLEDGE BADGE END -->


--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `litestar/_openapi/parameters.py`
Content:
```
1 from __future__ import annotations
2 
3 from typing import TYPE_CHECKING
4 
5 from litestar.constants import RESERVED_KWARGS
6 from litestar.enums import ParamType
7 from litestar.exceptions import ImproperlyConfiguredException
8 from litestar.openapi.spec.parameter import Parameter
9 from litestar.openapi.spec.schema import Schema
10 from litestar.params import DependencyKwarg, ParameterKwarg
11 from litestar.types import Empty
12 
13 __all__ = ("create_parameter_for_handler",)
14 
15 from litestar.typing import FieldDefinition
16 
17 if TYPE_CHECKING:
18     from litestar._openapi.schema_generation import SchemaCreator
19     from litestar.di import Provide
20     from litestar.handlers.base import BaseRouteHandler
21     from litestar.openapi.spec import Reference
22     from litestar.types.internal_types import PathParameterDefinition
23 
24 
25 class ParameterCollection:
26     """Facilitates conditional deduplication of parameters.
27 
28     If multiple parameters with the same name are produced for a handler, the condition is ignored if the two
29     ``Parameter`` instances are the same (the first is retained and any duplicates are ignored). If the ``Parameter``
30     instances are not the same, an exception is raised.
31     """
32 
33     def __init__(self, route_handler: BaseRouteHandler) -> None:
34         """Initialize ``ParameterCollection``.
35 
36         Args:
37             route_handler: Associated route handler
38         """
39         self.route_handler = route_handler
40         self._parameters: dict[str, Parameter] = {}
41 
42     def add(self, parameter: Parameter) -> None:
43         """Add a ``Parameter`` to the collection.
44 
45         If an existing parameter with the same name and type already exists, the
46         parameter is ignored.
47 
48         If an existing parameter with the same name but different type exists, raises
49         ``ImproperlyConfiguredException``.
50         """
51 
52         if parameter.name not in self._parameters:
53             # because we are defining routes as unique per path, we have to handle here a situation when there is an optional
54             # path parameter. e.g. get(path=["/", "/{param:str}"]). When parsing the parameter for path, the route handler
55             # would still have a kwarg called param:
56             # def handler(param: str | None) -> ...
57             if parameter.param_in != ParamType.QUERY or all(
58                 "{" + parameter.name + ":" not in path for path in self.route_handler.paths
59             ):
60                 self._parameters[parameter.name] = parameter
61             return
62 
63         pre_existing = self._parameters[parameter.name]
64         if parameter == pre_existing:
65             return
66 
67         raise ImproperlyConfiguredException(
68             f"OpenAPI schema generation for handler `{self.route_handler}` detected multiple parameters named "
69             f"'{parameter.name}' with different types."
70         )
71 
72     def list(self) -> list[Parameter]:
73         """Return a list of all ``Parameter``'s in the collection."""
74         return list(self._parameters.values())
75 
76 
77 def create_parameter(
78     field_definition: FieldDefinition,
79     parameter_name: str,
80     path_parameters: tuple[PathParameterDefinition, ...],
81     schema_creator: SchemaCreator,
82 ) -> Parameter:
83     """Create an OpenAPI Parameter instance."""
84 
85     result: Schema | Reference | None = None
86     kwarg_definition = (
87         field_definition.kwarg_definition if isinstance(field_definition.kwarg_definition, ParameterKwarg) else None
88     )
89 
90     if any(path_param.name == parameter_name for path_param in path_parameters):
91         param_in = ParamType.PATH
92         is_required = True
93         result = schema_creator.for_field_definition(field_definition)
94     elif kwarg_definition and kwarg_definition.header:
95         parameter_name = kwarg_definition.header
96         param_in = ParamType.HEADER
97         is_required = field_definition.is_required
98     elif kwarg_definition and kwarg_definition.cookie:
99         parameter_name = kwarg_definition.cookie
100         param_in = ParamType.COOKIE
101         is_required = field_definition.is_required
102     else:
103         is_required = field_definition.is_required
104         param_in = ParamType.QUERY
105         parameter_name = kwarg_definition.query if kwarg_definition and kwarg_definition.query else parameter_name
106 
107     if not result:
108         result = schema_creator.for_field_definition(field_definition)
109 
110     schema = result if isinstance(result, Schema) else schema_creator.schemas[result.value]
111 
112     return Parameter(
113         description=schema.description,
114         name=parameter_name,
115         param_in=param_in,
116         required=is_required,
117         schema=result,
118     )
119 
120 
121 def get_recursive_handler_parameters(
122     field_name: str,
123     field_definition: FieldDefinition,
124     dependency_providers: dict[str, Provide],
125     route_handler: BaseRouteHandler,
126     path_parameters: tuple[PathParameterDefinition, ...],
127     schema_creator: SchemaCreator,
128 ) -> list[Parameter]:
129     """Create and return parameters for a handler.
130 
131     If the provided field is not a dependency, a normal parameter is created and returned as a list, otherwise
132     `create_parameter_for_handler()` is called to generate parameters for the dependency.
133     """
134 
135     if field_name not in dependency_providers:
136         return [
137             create_parameter(
138                 field_definition=field_definition,
139                 parameter_name=field_name,
140                 path_parameters=path_parameters,
141                 schema_creator=schema_creator,
142             )
143         ]
144 
145     dependency_fields = dependency_providers[field_name].signature_model._fields
146     return create_parameter_for_handler(
147         route_handler=route_handler,
148         handler_fields=dependency_fields,
149         path_parameters=path_parameters,
150         schema_creator=schema_creator,
151     )
152 
153 
154 def get_layered_parameter(
155     field_name: str,
156     field_definition: FieldDefinition,
157     layered_parameters: dict[str, FieldDefinition],
158     path_parameters: tuple[PathParameterDefinition, ...],
159     schema_creator: SchemaCreator,
160 ) -> Parameter:
161     """Create a layered parameter for a given signature model field.
162 
163     Layer info is extracted from the provided ``layered_parameters`` dict and set as the field's ``field_info`` attribute.
164     """
165     layer_field = layered_parameters[field_name]
166 
167     field = field_definition if field_definition.is_parameter_field else layer_field
168     default = layer_field.default if field_definition.has_default else field_definition.default
169     annotation = field_definition.annotation if field_definition is not Empty else layer_field.annotation
170 
171     parameter_name = field_name
172     if isinstance(field.kwarg_definition, ParameterKwarg):
173         parameter_name = (
174             field.kwarg_definition.query or field.kwarg_definition.header or field.kwarg_definition.cookie or field_name
175         )
176 
177     field_definition = FieldDefinition.from_kwarg(
178         inner_types=field.inner_types,
179         default=default,
180         extra=field.extra,
181         annotation=annotation,
182         kwarg_definition=field.kwarg_definition,
183         name=field_name,
184     )
185     return create_parameter(
186         field_definition=field_definition,
187         parameter_name=parameter_name,
188         path_parameters=path_parameters,
189         schema_creator=schema_creator,
190     )
191 
192 
193 def create_parameter_for_handler(
194     route_handler: BaseRouteHandler,
195     handler_fields: dict[str, FieldDefinition],
196     path_parameters: tuple[PathParameterDefinition, ...],
197     schema_creator: SchemaCreator,
198 ) -> list[Parameter]:
199     """Create a list of path/query/header Parameter models for the given PathHandler."""
200     parameters = ParameterCollection(route_handler=route_handler)
201     dependency_providers = route_handler.resolve_dependencies()
202     layered_parameters = route_handler.resolve_layered_parameters()
203 
204     unique_handler_fields = tuple(
205         (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k not in layered_parameters
206     )
207     unique_layered_fields = tuple(
208         (k, v) for k, v in layered_parameters.items() if k not in RESERVED_KWARGS and k not in handler_fields
209     )
210     intersection_fields = tuple(
211         (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k in layered_parameters
212     )
213 
214     for field_name, field_definition in unique_handler_fields:
215         if isinstance(field_definition.kwarg_definition, DependencyKwarg) and field_name not in dependency_providers:
216             # never document explicit dependencies
217             continue
218 
219         for parameter in get_recursive_handler_parameters(
220             field_name=field_name,
221             field_definition=field_definition,
222             dependency_providers=dependency_providers,
223             route_handler=route_handler,
224             path_parameters=path_parameters,
225             schema_creator=schema_creator,
226         ):
227             parameters.add(parameter)
228 
229     for field_name, field_definition in unique_layered_fields:
230         parameters.add(
231             create_parameter(
232                 field_definition=field_definition,
233                 parameter_name=field_name,
234                 path_parameters=path_parameters,
235                 schema_creator=schema_creator,
236             )
237         )
238 
239     for field_name, field_definition in intersection_fields:
240         parameters.add(
241             get_layered_parameter(
242                 field_name=field_name,
243                 field_definition=field_definition,
244                 layered_parameters=layered_parameters,
245                 path_parameters=path_parameters,
246                 schema_creator=schema_creator,
247             )
248         )
249 
250     return parameters.list()
251
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/litestar/_openapi/parameters.py b/litestar/_openapi/parameters.py
--- a/litestar/_openapi/parameters.py
+++ b/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 @@
 
     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,
     )

{"golden_diff": "diff --git a/litestar/_openapi/parameters.py b/litestar/_openapi/parameters.py\n--- a/litestar/_openapi/parameters.py\n+++ b/litestar/_openapi/parameters.py\n@@ -18,7 +18,7 @@\n     from litestar._openapi.schema_generation import SchemaCreator\n     from litestar.di import Provide\n     from litestar.handlers.base import BaseRouteHandler\n-    from litestar.openapi.spec import Reference\n+    from litestar.openapi.spec import Example, Reference\n     from litestar.types.internal_types import PathParameterDefinition\n \n \n@@ -109,12 +109,17 @@\n \n     schema = result if isinstance(result, Schema) else schema_creator.schemas[result.value]\n \n+    examples: dict[str, Example | Reference] = {}\n+    for i, example in enumerate(kwarg_definition.examples or [] if kwarg_definition else []):\n+        examples[f\"{field_definition.name}-example-{i}\"] = example\n+\n     return Parameter(\n         description=schema.description,\n         name=parameter_name,\n         param_in=param_in,\n         required=is_required,\n         schema=result,\n+        examples=examples or None,\n     )\n", "issue": "Bug: Wrong OpenAPI `examples` format and nesting\n### Description\r\n\r\nFor examples to show up on SwaggerUI, the `examples` array should be an object and nested on the same level as `schema`, not under it.\r\n\r\nWrong definition:\r\n```json\r\n{\r\n  \"parameters\": [\r\n    {\r\n      \"schema\": {\r\n        \"type\": \"string\",\r\n        \"examples\": [\r\n          {\r\n            \"summary\": \"example summary\",\r\n            \"value\": \"example value\"\r\n          }\r\n        ]\r\n      }\r\n    }\r\n  ]\r\n}\r\n````\r\n\r\nCorrect definition:\r\n```json\r\n{\r\n  \"parameters\": [\r\n    {\r\n      \"schema\": {\r\n        \"type\": \"string\"\r\n      },\r\n\t  \"examples\": {\r\n        \"example1\": {\r\n          \"summary\": \"example summary\"\r\n          \"value\": \"example value\"\r\n        }\r\n      }\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n### MCVE\r\n\r\n```python\r\nfrom litestar import Litestar, get\r\nfrom litestar.openapi import OpenAPIConfig\r\nfrom litestar.openapi.spec.example import Example\r\nfrom litestar.params import Parameter\r\n\r\nfrom typing import Annotated\r\n\r\n\r\n@get(path=\"/\")\r\nasync def index(\r\n    text: Annotated[\r\n        str,\r\n        Parameter(\r\n            examples=[Example(value=\"example value\", summary=\"example summary\")]\r\n        )\r\n    ]\r\n) -> str:\r\n    return text\r\n\r\napp = Litestar(\r\n    route_handlers=[\r\n        index\r\n    ],\r\n    openapi_config=OpenAPIConfig(\r\n        title=\"Test API\",\r\n        version=\"1.0.0\"\r\n    )\r\n)\r\n```\r\n\r\n\r\n### Steps to reproduce\r\n\r\n```bash\r\n1. Go to the SwaggerUI docs.\r\n2. Click on the `index` GET method.\r\n3. See that there are no examples under the `text` query parameter.\r\n```\r\n\r\n\r\n### Screenshots\r\n\r\n![SwaggerUI query](https://github.com/litestar-org/litestar/assets/24798198/37dadcf0-7d5b-49c3-91e6-01c3bdd4137c)\r\n\r\n### Litestar Version\r\n\r\n2.1.1\r\n\r\n### Platform\r\n\r\n- [ ] Linux\r\n- [ ] Mac\r\n- [X] Windows\r\n- [ ] Other (Please specify in the description above)\r\n\r\n<!-- POLAR PLEDGE BADGE START -->\r\n---\r\n> [!NOTE]  \r\n> While we are open for sponsoring on [GitHub Sponsors](https://github.com/sponsors/litestar-org/) and \r\n> [OpenCollective](https://opencollective.com/litestar), we also utilize [Polar.sh](https://polar.sh/) to engage in pledge-based sponsorship.\r\n>\r\n> Check out all issues funded or available for funding [on our Polar.sh Litestar dashboard](https://polar.sh/litestar-org)\r\n> * If you would like to see an issue prioritized, make a pledge towards it!\r\n> * We receive the pledge once the issue is completed & verified\r\n> * This, along with engagement in the community, helps us know which features are a priority to our users.\r\n\r\n<a href=\"https://polar.sh/litestar-org/litestar/issues/2494\">\r\n<picture>\r\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://polar.sh/api/github/litestar-org/litestar/issues/2494/pledge.svg?darkmode=1\">\r\n  <img alt=\"Fund with Polar\" src=\"https://polar.sh/api/github/litestar-org/litestar/issues/2494/pledge.svg\">\r\n</picture>\r\n</a>\r\n<!-- POLAR PLEDGE BADGE END -->\r\n\n", "before_files": [{"content": "from __future__ import annotations\n\nfrom typing import TYPE_CHECKING\n\nfrom litestar.constants import RESERVED_KWARGS\nfrom litestar.enums import ParamType\nfrom litestar.exceptions import ImproperlyConfiguredException\nfrom litestar.openapi.spec.parameter import Parameter\nfrom litestar.openapi.spec.schema import Schema\nfrom litestar.params import DependencyKwarg, ParameterKwarg\nfrom litestar.types import Empty\n\n__all__ = (\"create_parameter_for_handler\",)\n\nfrom litestar.typing import FieldDefinition\n\nif TYPE_CHECKING:\n    from litestar._openapi.schema_generation import SchemaCreator\n    from litestar.di import Provide\n    from litestar.handlers.base import BaseRouteHandler\n    from litestar.openapi.spec import Reference\n    from litestar.types.internal_types import PathParameterDefinition\n\n\nclass ParameterCollection:\n    \"\"\"Facilitates conditional deduplication of parameters.\n\n    If multiple parameters with the same name are produced for a handler, the condition is ignored if the two\n    ``Parameter`` instances are the same (the first is retained and any duplicates are ignored). If the ``Parameter``\n    instances are not the same, an exception is raised.\n    \"\"\"\n\n    def __init__(self, route_handler: BaseRouteHandler) -> None:\n        \"\"\"Initialize ``ParameterCollection``.\n\n        Args:\n            route_handler: Associated route handler\n        \"\"\"\n        self.route_handler = route_handler\n        self._parameters: dict[str, Parameter] = {}\n\n    def add(self, parameter: Parameter) -> None:\n        \"\"\"Add a ``Parameter`` to the collection.\n\n        If an existing parameter with the same name and type already exists, the\n        parameter is ignored.\n\n        If an existing parameter with the same name but different type exists, raises\n        ``ImproperlyConfiguredException``.\n        \"\"\"\n\n        if parameter.name not in self._parameters:\n            # because we are defining routes as unique per path, we have to handle here a situation when there is an optional\n            # path parameter. e.g. get(path=[\"/\", \"/{param:str}\"]). When parsing the parameter for path, the route handler\n            # would still have a kwarg called param:\n            # def handler(param: str | None) -> ...\n            if parameter.param_in != ParamType.QUERY or all(\n                \"{\" + parameter.name + \":\" not in path for path in self.route_handler.paths\n            ):\n                self._parameters[parameter.name] = parameter\n            return\n\n        pre_existing = self._parameters[parameter.name]\n        if parameter == pre_existing:\n            return\n\n        raise ImproperlyConfiguredException(\n            f\"OpenAPI schema generation for handler `{self.route_handler}` detected multiple parameters named \"\n            f\"'{parameter.name}' with different types.\"\n        )\n\n    def list(self) -> list[Parameter]:\n        \"\"\"Return a list of all ``Parameter``'s in the collection.\"\"\"\n        return list(self._parameters.values())\n\n\ndef create_parameter(\n    field_definition: FieldDefinition,\n    parameter_name: str,\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> Parameter:\n    \"\"\"Create an OpenAPI Parameter instance.\"\"\"\n\n    result: Schema | Reference | None = None\n    kwarg_definition = (\n        field_definition.kwarg_definition if isinstance(field_definition.kwarg_definition, ParameterKwarg) else None\n    )\n\n    if any(path_param.name == parameter_name for path_param in path_parameters):\n        param_in = ParamType.PATH\n        is_required = True\n        result = schema_creator.for_field_definition(field_definition)\n    elif kwarg_definition and kwarg_definition.header:\n        parameter_name = kwarg_definition.header\n        param_in = ParamType.HEADER\n        is_required = field_definition.is_required\n    elif kwarg_definition and kwarg_definition.cookie:\n        parameter_name = kwarg_definition.cookie\n        param_in = ParamType.COOKIE\n        is_required = field_definition.is_required\n    else:\n        is_required = field_definition.is_required\n        param_in = ParamType.QUERY\n        parameter_name = kwarg_definition.query if kwarg_definition and kwarg_definition.query else parameter_name\n\n    if not result:\n        result = schema_creator.for_field_definition(field_definition)\n\n    schema = result if isinstance(result, Schema) else schema_creator.schemas[result.value]\n\n    return Parameter(\n        description=schema.description,\n        name=parameter_name,\n        param_in=param_in,\n        required=is_required,\n        schema=result,\n    )\n\n\ndef get_recursive_handler_parameters(\n    field_name: str,\n    field_definition: FieldDefinition,\n    dependency_providers: dict[str, Provide],\n    route_handler: BaseRouteHandler,\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> list[Parameter]:\n    \"\"\"Create and return parameters for a handler.\n\n    If the provided field is not a dependency, a normal parameter is created and returned as a list, otherwise\n    `create_parameter_for_handler()` is called to generate parameters for the dependency.\n    \"\"\"\n\n    if field_name not in dependency_providers:\n        return [\n            create_parameter(\n                field_definition=field_definition,\n                parameter_name=field_name,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        ]\n\n    dependency_fields = dependency_providers[field_name].signature_model._fields\n    return create_parameter_for_handler(\n        route_handler=route_handler,\n        handler_fields=dependency_fields,\n        path_parameters=path_parameters,\n        schema_creator=schema_creator,\n    )\n\n\ndef get_layered_parameter(\n    field_name: str,\n    field_definition: FieldDefinition,\n    layered_parameters: dict[str, FieldDefinition],\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> Parameter:\n    \"\"\"Create a layered parameter for a given signature model field.\n\n    Layer info is extracted from the provided ``layered_parameters`` dict and set as the field's ``field_info`` attribute.\n    \"\"\"\n    layer_field = layered_parameters[field_name]\n\n    field = field_definition if field_definition.is_parameter_field else layer_field\n    default = layer_field.default if field_definition.has_default else field_definition.default\n    annotation = field_definition.annotation if field_definition is not Empty else layer_field.annotation\n\n    parameter_name = field_name\n    if isinstance(field.kwarg_definition, ParameterKwarg):\n        parameter_name = (\n            field.kwarg_definition.query or field.kwarg_definition.header or field.kwarg_definition.cookie or field_name\n        )\n\n    field_definition = FieldDefinition.from_kwarg(\n        inner_types=field.inner_types,\n        default=default,\n        extra=field.extra,\n        annotation=annotation,\n        kwarg_definition=field.kwarg_definition,\n        name=field_name,\n    )\n    return create_parameter(\n        field_definition=field_definition,\n        parameter_name=parameter_name,\n        path_parameters=path_parameters,\n        schema_creator=schema_creator,\n    )\n\n\ndef create_parameter_for_handler(\n    route_handler: BaseRouteHandler,\n    handler_fields: dict[str, FieldDefinition],\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> list[Parameter]:\n    \"\"\"Create a list of path/query/header Parameter models for the given PathHandler.\"\"\"\n    parameters = ParameterCollection(route_handler=route_handler)\n    dependency_providers = route_handler.resolve_dependencies()\n    layered_parameters = route_handler.resolve_layered_parameters()\n\n    unique_handler_fields = tuple(\n        (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k not in layered_parameters\n    )\n    unique_layered_fields = tuple(\n        (k, v) for k, v in layered_parameters.items() if k not in RESERVED_KWARGS and k not in handler_fields\n    )\n    intersection_fields = tuple(\n        (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k in layered_parameters\n    )\n\n    for field_name, field_definition in unique_handler_fields:\n        if isinstance(field_definition.kwarg_definition, DependencyKwarg) and field_name not in dependency_providers:\n            # never document explicit dependencies\n            continue\n\n        for parameter in get_recursive_handler_parameters(\n            field_name=field_name,\n            field_definition=field_definition,\n            dependency_providers=dependency_providers,\n            route_handler=route_handler,\n            path_parameters=path_parameters,\n            schema_creator=schema_creator,\n        ):\n            parameters.add(parameter)\n\n    for field_name, field_definition in unique_layered_fields:\n        parameters.add(\n            create_parameter(\n                field_definition=field_definition,\n                parameter_name=field_name,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        )\n\n    for field_name, field_definition in intersection_fields:\n        parameters.add(\n            get_layered_parameter(\n                field_name=field_name,\n                field_definition=field_definition,\n                layered_parameters=layered_parameters,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        )\n\n    return parameters.list()\n", "path": "litestar/_openapi/parameters.py"}], "after_files": [{"content": "from __future__ import annotations\n\nfrom typing import TYPE_CHECKING\n\nfrom litestar.constants import RESERVED_KWARGS\nfrom litestar.enums import ParamType\nfrom litestar.exceptions import ImproperlyConfiguredException\nfrom litestar.openapi.spec.parameter import Parameter\nfrom litestar.openapi.spec.schema import Schema\nfrom litestar.params import DependencyKwarg, ParameterKwarg\nfrom litestar.types import Empty\n\n__all__ = (\"create_parameter_for_handler\",)\n\nfrom litestar.typing import FieldDefinition\n\nif TYPE_CHECKING:\n    from litestar._openapi.schema_generation import SchemaCreator\n    from litestar.di import Provide\n    from litestar.handlers.base import BaseRouteHandler\n    from litestar.openapi.spec import Example, Reference\n    from litestar.types.internal_types import PathParameterDefinition\n\n\nclass ParameterCollection:\n    \"\"\"Facilitates conditional deduplication of parameters.\n\n    If multiple parameters with the same name are produced for a handler, the condition is ignored if the two\n    ``Parameter`` instances are the same (the first is retained and any duplicates are ignored). If the ``Parameter``\n    instances are not the same, an exception is raised.\n    \"\"\"\n\n    def __init__(self, route_handler: BaseRouteHandler) -> None:\n        \"\"\"Initialize ``ParameterCollection``.\n\n        Args:\n            route_handler: Associated route handler\n        \"\"\"\n        self.route_handler = route_handler\n        self._parameters: dict[str, Parameter] = {}\n\n    def add(self, parameter: Parameter) -> None:\n        \"\"\"Add a ``Parameter`` to the collection.\n\n        If an existing parameter with the same name and type already exists, the\n        parameter is ignored.\n\n        If an existing parameter with the same name but different type exists, raises\n        ``ImproperlyConfiguredException``.\n        \"\"\"\n\n        if parameter.name not in self._parameters:\n            # because we are defining routes as unique per path, we have to handle here a situation when there is an optional\n            # path parameter. e.g. get(path=[\"/\", \"/{param:str}\"]). When parsing the parameter for path, the route handler\n            # would still have a kwarg called param:\n            # def handler(param: str | None) -> ...\n            if parameter.param_in != ParamType.QUERY or all(\n                \"{\" + parameter.name + \":\" not in path for path in self.route_handler.paths\n            ):\n                self._parameters[parameter.name] = parameter\n            return\n\n        pre_existing = self._parameters[parameter.name]\n        if parameter == pre_existing:\n            return\n\n        raise ImproperlyConfiguredException(\n            f\"OpenAPI schema generation for handler `{self.route_handler}` detected multiple parameters named \"\n            f\"'{parameter.name}' with different types.\"\n        )\n\n    def list(self) -> list[Parameter]:\n        \"\"\"Return a list of all ``Parameter``'s in the collection.\"\"\"\n        return list(self._parameters.values())\n\n\ndef create_parameter(\n    field_definition: FieldDefinition,\n    parameter_name: str,\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> Parameter:\n    \"\"\"Create an OpenAPI Parameter instance.\"\"\"\n\n    result: Schema | Reference | None = None\n    kwarg_definition = (\n        field_definition.kwarg_definition if isinstance(field_definition.kwarg_definition, ParameterKwarg) else None\n    )\n\n    if any(path_param.name == parameter_name for path_param in path_parameters):\n        param_in = ParamType.PATH\n        is_required = True\n        result = schema_creator.for_field_definition(field_definition)\n    elif kwarg_definition and kwarg_definition.header:\n        parameter_name = kwarg_definition.header\n        param_in = ParamType.HEADER\n        is_required = field_definition.is_required\n    elif kwarg_definition and kwarg_definition.cookie:\n        parameter_name = kwarg_definition.cookie\n        param_in = ParamType.COOKIE\n        is_required = field_definition.is_required\n    else:\n        is_required = field_definition.is_required\n        param_in = ParamType.QUERY\n        parameter_name = kwarg_definition.query if kwarg_definition and kwarg_definition.query else parameter_name\n\n    if not result:\n        result = schema_creator.for_field_definition(field_definition)\n\n    schema = result if isinstance(result, Schema) else schema_creator.schemas[result.value]\n\n    examples: dict[str, Example | Reference] = {}\n    for i, example in enumerate(kwarg_definition.examples or [] if kwarg_definition else []):\n        examples[f\"{field_definition.name}-example-{i}\"] = example\n\n    return Parameter(\n        description=schema.description,\n        name=parameter_name,\n        param_in=param_in,\n        required=is_required,\n        schema=result,\n        examples=examples or None,\n    )\n\n\ndef get_recursive_handler_parameters(\n    field_name: str,\n    field_definition: FieldDefinition,\n    dependency_providers: dict[str, Provide],\n    route_handler: BaseRouteHandler,\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> list[Parameter]:\n    \"\"\"Create and return parameters for a handler.\n\n    If the provided field is not a dependency, a normal parameter is created and returned as a list, otherwise\n    `create_parameter_for_handler()` is called to generate parameters for the dependency.\n    \"\"\"\n\n    if field_name not in dependency_providers:\n        return [\n            create_parameter(\n                field_definition=field_definition,\n                parameter_name=field_name,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        ]\n\n    dependency_fields = dependency_providers[field_name].signature_model._fields\n    return create_parameter_for_handler(\n        route_handler=route_handler,\n        handler_fields=dependency_fields,\n        path_parameters=path_parameters,\n        schema_creator=schema_creator,\n    )\n\n\ndef get_layered_parameter(\n    field_name: str,\n    field_definition: FieldDefinition,\n    layered_parameters: dict[str, FieldDefinition],\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> Parameter:\n    \"\"\"Create a layered parameter for a given signature model field.\n\n    Layer info is extracted from the provided ``layered_parameters`` dict and set as the field's ``field_info`` attribute.\n    \"\"\"\n    layer_field = layered_parameters[field_name]\n\n    field = field_definition if field_definition.is_parameter_field else layer_field\n    default = layer_field.default if field_definition.has_default else field_definition.default\n    annotation = field_definition.annotation if field_definition is not Empty else layer_field.annotation\n\n    parameter_name = field_name\n    if isinstance(field.kwarg_definition, ParameterKwarg):\n        parameter_name = (\n            field.kwarg_definition.query or field.kwarg_definition.header or field.kwarg_definition.cookie or field_name\n        )\n\n    field_definition = FieldDefinition.from_kwarg(\n        inner_types=field.inner_types,\n        default=default,\n        extra=field.extra,\n        annotation=annotation,\n        kwarg_definition=field.kwarg_definition,\n        name=field_name,\n    )\n    return create_parameter(\n        field_definition=field_definition,\n        parameter_name=parameter_name,\n        path_parameters=path_parameters,\n        schema_creator=schema_creator,\n    )\n\n\ndef create_parameter_for_handler(\n    route_handler: BaseRouteHandler,\n    handler_fields: dict[str, FieldDefinition],\n    path_parameters: tuple[PathParameterDefinition, ...],\n    schema_creator: SchemaCreator,\n) -> list[Parameter]:\n    \"\"\"Create a list of path/query/header Parameter models for the given PathHandler.\"\"\"\n    parameters = ParameterCollection(route_handler=route_handler)\n    dependency_providers = route_handler.resolve_dependencies()\n    layered_parameters = route_handler.resolve_layered_parameters()\n\n    unique_handler_fields = tuple(\n        (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k not in layered_parameters\n    )\n    unique_layered_fields = tuple(\n        (k, v) for k, v in layered_parameters.items() if k not in RESERVED_KWARGS and k not in handler_fields\n    )\n    intersection_fields = tuple(\n        (k, v) for k, v in handler_fields.items() if k not in RESERVED_KWARGS and k in layered_parameters\n    )\n\n    for field_name, field_definition in unique_handler_fields:\n        if isinstance(field_definition.kwarg_definition, DependencyKwarg) and field_name not in dependency_providers:\n            # never document explicit dependencies\n            continue\n\n        for parameter in get_recursive_handler_parameters(\n            field_name=field_name,\n            field_definition=field_definition,\n            dependency_providers=dependency_providers,\n            route_handler=route_handler,\n            path_parameters=path_parameters,\n            schema_creator=schema_creator,\n        ):\n            parameters.add(parameter)\n\n    for field_name, field_definition in unique_layered_fields:\n        parameters.add(\n            create_parameter(\n                field_definition=field_definition,\n                parameter_name=field_name,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        )\n\n    for field_name, field_definition in intersection_fields:\n        parameters.add(\n            get_layered_parameter(\n                field_name=field_name,\n                field_definition=field_definition,\n                layered_parameters=layered_parameters,\n                path_parameters=path_parameters,\n                schema_creator=schema_creator,\n            )\n        )\n\n    return parameters.list()\n", "path": "litestar/_openapi/parameters.py"}]}