feat: pass examples given in the FieldDefinition to the OpenAPIMediaType

[robswc]

New PR, based off of: #3128

Description

• Passes examples given within the FieldDefinition to the OpenAPIMediaType

@post(media_type=MediaType.TEXT)
def create_person(
    self, data: Annotated[DataclassPerson, Body(examples=[Example(summary="this is an example", value={"key": "value"})])], secret_header: str = Parameter(header="secret")
) -> DataclassPerson:
    return data

Fixes

Fixes #3076

[codecov]

Codecov Report

Attention: Patch coverage is 70.58824% with 5 lines in your changes are missing coverage. Please review.

Project coverage is 98.23%. Comparing base (43e3041) to head (58108c0).

Files	Patch %	Lines
litestar/_openapi/schema_generation/schema.py	60.00%	2 Missing and 2 partials ⚠️
litestar/_openapi/request_body.py	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             v3.0    #3222      +/-   ##
==========================================
- Coverage   98.26%   98.23%   -0.04%     
==========================================
  Files         322      322              
  Lines       14733    14749      +16     
  Branches     2343     2352       +9     
==========================================
+ Hits        14477    14488      +11     
- Misses        117      119       +2     
- Partials      139      142       +3     

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

[robswc]

Original review/suggestions:

#3128 (review)

[robswc]

@provinzkraut Hey! It has been awhile since I have worked on this feature. I had to create a new PR as I had some issues with the way I originally forked the project.

That said, I have made the changes you mentioned in your review here:

#3128 (review)

Tests and pre-commits seem to pass but I get mypy and pyright errors. I remember now that is why I added some of the things I did. Was looking for further feedback on how to proceed. Thanks!

[peterschutt]

Do you still get errors from type checking if you run the checks on python 3.8? Nvm - I see they are occurring in CI.

[robswc]

Hey! If anyone could check this out it would be much appreciated!

I get this failure in the type-checking CI:

error: Argument "examples" to "OpenAPIMediaType" has incompatible type "Optional[Mapping[str, Example]]"; expected "Optional[Dict[str, Union[Example, Reference]]]

https://github.com/litestar-org/litestar/actions/runs/8480802759/job/23237155365?pr=3222#step:6:18

I had previously changed the types:

 -  examples: dict[str, Example | Reference] | None = None
 +  examples: dict[str, Example | Reference] | Mapping[str, Example] | None = None

provinzkraut pointed out the following, which I agree with:

While I think this is a good change, it's unfortunately breaking; If someone is using this attribute and referring to dict-only methods on it, passing a different type of mapping here would break their code and also their type checking.

However, I'm not sure how to proceed.

Thanks!

[provinzkraut]

However, I'm not sure how to proceed.

There are 2 options:

1. Figure out how to accomplish this without breaking changes
2. Point the PR to the v3.0 branch

---

(also, if you @-tag me, it's easier to see something needs my attention 🙂)

[robswc]

However, I'm not sure how to proceed.

There are 2 options:

1. Figure out how to accomplish this without breaking changes
2. Point the PR to the v3.0 branch

(also, if you @-tag me, it's easier to see something needs my attention 🙂)

Awesome! I try to avoid @-ing unless its urgent but I'll keep it in mind! Thanks for your suggestions, I will try pointing to v3.0

[github-actions]

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

[robswc]

@provinzkraut - does this look ok 😅 ? I followed the suggestion of rebasing. Everything appears to be in order but I'm inexperienced with rebasing. It says 26 files have changed when, IIRC, I only changed ~3.

Thanks again for the feedback/back and forth!