Properly rebuild Pydantic models if necessary

[Viicos]

This is the alternative approach I mentioned in #1171 (comment).

Instead of trying to rebuild the models in their respective modules (which requires weird patterns, such as unused imports or importing after the model is defined), we set defer_build to True for every model where we know a forward reference will fail to resolve (so that we don't try to build a model if we know it will fail).

I added comments each time to justify the use of defer_build, but unfortunately this isn't always straightforward (e.g. sometimes you makes use of a model as annotation which itself has defer_build set; in this case we also want to defer build. Another case is when making use of the Callback type alias; it isn't directly visible but it uses an unresolvable forward reference).

Ultimately, in the module's __init__.py, we call model_rebuild on all the necessary models. I know this isn't ideal as well, as you need to manually check for every exported model here if the build was successful.

This library is a clear example that inter-dependent types across different modules is challenging, and Pydantic does not make it easy. We are trying to think about ways to simplify the process.

Note that on top of fixing things for Pydantic 2.10, this also ensures every model is successfully built when the openapi_schema_pydantic module is imported. Currently on main (with Pydantic 2.9.2), some models such as Components are not built. While this can still work in some cases, it is advised not to do so (when Components is going to be instantiated, Pydantic will implicitly try to rebuild it if it wasn't already. However, we use the namespace where the instantiation call happened to rebuilt it, so depending on where you first instantiate the model, this can lead to a failed model rebuild and thus a runtime exception).

---

A note on model_rebuild: you can either provide an explicit namespace:

PathItem.model_rebuild(_types_namespace={Operation: "Operation", "Header": Header})

Or let model_rebuild use the namespace where it was called (in our case, all the imports are available, so it works).

[eli-bl]

@Viicos, currently there are some linter failures— you'll want to do pdm lint && pdm format && pdm mypy.

Changes have been addressed

[dbanty]

Thanks so much for submitting the fix!