fix: openapi generation with pydantic examples

[bunny-therapist]

Description

Resolves an issue with OpenAPI schema generation when using Pydantic examples

Closes

• Closes Bug: schema generation crashes in 2.7.1 #3277

[bunny-therapist]

I am not entirely sure about treating the examples as Example objects or just include them raw, but then again, this is arguably more strict than casting something to list[Example] that apparently was sometimes not that all, but e.g. list[str]. I don't quite understand the (apparently faulty) logic of the casting; I just made this work by not crashing if the elements are not Example objects (which is probably better than crashing).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.23%. Comparing base (d2cb891) to head (930412c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3279   +/-   ##
=======================================
  Coverage   98.23%   98.23%           
=======================================
  Files         320      320           
  Lines       14448    14449    +1     
  Branches     2296     2296           
=======================================
+ Hits        14193    14194    +1     
  Misses        114      114           
  Partials      141      141           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/3279

[peterschutt]

The issue is really in:

litestar/litestar/typing.py

Line 81 in d2cb891

def _parse_metadata(value: Any, is_sequence_container: bool, extra: dict[str, Any] | None) -> dict[str, Any]:

... where the schema properties such as examples, are unpacked into an instance of KwargDefinition.

Here, the json_schema_extra is unpacked into a dict:

litestar/litestar/typing.py

Lines 92 to 95 in d2cb891

	extra = {
	**cast("dict[str, Any]", extra or getattr(value, "extra", None) or {}),
	**(getattr(value, "json_schema_extra", None) or {}),
	}

Then the list of Example object is constructed:

litestar/litestar/typing.py

Lines 96 to 102 in d2cb891

	example_list: list[Any] | None
	if example := extra.pop("example", None):
	example_list = [Example(value=example)]
	elif examples := getattr(value, "examples", None):
	example_list = [Example(value=example) for example in cast("list[str]", examples)]
	else:
	example_list = None

However, extra is only checked to see if it contains "example", not "examples", so example_list is None and "examples" remains in the extra dict - and at this point examples could contain anything.

Then, that extra dict is unpacked into the dict returned from that function:

litestar/litestar/typing.py

Line 127 in d2cb891

**extra,

Eventually the dict returned which now contains "examples": ["example"] is used to instantiate the KwargDefinition here:

litestar/litestar/typing.py

Line 176 in d2cb891

return model(**constraints) if constraints else None, extra

And that is the problem, KwargDefinition.examples is typed list[Example] - not list[Any] but we are instantiating it with whatever json_schema_extra["examples"] is set to because we don't pop them from that extra dict as pointed out above.

We actually spoke about this in #3224 (that is carrying around jsonschema examples in openapi spec example objects. Not ideal but its a legacy thing).

This is why that list[Example] typing exists that you question above.

This metadata handling is an absolute labyrinth so no judgement about the fix you applied in this PR, but I think resolving this per above is preferable.

[peterschutt]

Superseded by #3281 - copied your test over with attribution and applied the fix @bunny-therapist - cheers!