Setting an example value for a field in response object generates deprecation warnings with pydantic >= 2.5

[guillaume-alvarez]

Environment:

• Python version: 3.12.3
• Operating system: Ubuntu
• Flask version: 2.3.3
• flask-openapi3 version: 3.1.3

Warning

If I define a model setting Field.example (not defined in pydantic):

class MyResponse(BaseModel):
    stream_id: str = Field(..., example="some_stream")

then it causes warnings because it is not officially supported by pydantic:

PydanticDeprecatedSince20: Using extra keyword arguments on `Field` is deprecated and will be removed. Use `json_schema_extra` instead. (Extra keys: 'example'). Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.9/migration/

Error

If I define a model setting the Field.examples as advised by pydantic:

class MyResponse(BaseModel):
    stream_id: str = Field(..., examples="some_stream")

Then the examples value does not appear in the resulting OpenAPI schema.

This field was added in pydantic 2.5.0 by pydantic/pydantic#8013

According to OpenAPI 3.1.0 specs, the use of example is deprecated:

Deprecated: The example property has been deprecated in favor of the JSON Schema examples keyword. Use of example is discouraged, and later versions of this specification may remove it.

Debugging the code I see that the 'examples' value is present in the json schema generated by pydantic but removed by flask_openapi3 when converting to the Schema model. It only defines an example and no examples.

I think the simplest fix would be to add a Schema.examples field in flask_openapi3/models/schema.py.