Generate the schema of a response model by property names

[candleindark]

Currently, the schema of a Pydantic model that is specified as a response is generated using aliases in the model as the keys (per the default behavior of a Pydantic model). Can we have a feature in flask-openapi3 that allows the schema of a Pydantic model that is specified as a response to be generated using the property names of the model (as MainModel. schema_json(by_alias=False))?

[luolingchun]

@candleindark We can add by_alias in Model Config, demo:

class BookQuery(BaseModel):
    age: int
    author: str

    class Config:
        by_alias = False

    # in pydantic v2.x
    model_config = ConfigDict(by_alias=False)

Then using by_alias in get_schema.

def get_schema(obj: Type[BaseModel]) -> dict:
    """Converts a Pydantic model to an OpenAPI schema."""

    assert inspect.isclass(obj) and issubclass(obj, BaseModel), \
        f"{obj} is invalid `pydantic.BaseModel`"
   
    model_config = response.Config
    by_alias = getattr(model_config, "by_alias", True)

    return obj.schema(by_alias=False, ref_template=OPENAPI3_REF_TEMPLATE)

Is this what you think?

[candleindark]

Generally, yes. However, I have one concern and one possible correction.

• The concern:

  • I am concerned about using the by_alias field in the Config class of a Pydantic model. Using this field may come into conflict with the future version of Pydantic or some other extension of Pydantic. To avoid such a potential conflict, shouldn't we at least prefix the field name? For example, we can use flask_openapi3_schema_by_alias instead of just by_alias.

• The correction

  • If I get your intent correctly, I think the get_schema has some minor issues. The following is the corrected version.

def get_schema(obj: Type[BaseModel]) -> dict:
    """Converts a Pydantic model to an OpenAPI schema."""

    assert inspect.isclass(obj) and issubclass(obj, BaseModel), \
        f"{obj} is invalid `pydantic.BaseModel`"
   
    model_config = obj.Config
    by_alias = getattr(model_config, "by_alias", True)

    return obj.schema(by_alias=by_alias, ref_template=OPENAPI3_REF_TEMPLATE)

[luolingchun]

@candleindark Thanks for your correction.

flask_openapi3_schema_by_alias is too long, and I think in the future, even if Pydantic or other extensions support by_alias will also have the same effect.

Additionally, can you write a simple example so that we can provide better documentation.

[candleindark]

flask_openapi3_schema_by_alias is indeed long. It is just an example. You can choose a shorter prefix. However, whether to chose a prefix or now, the final decision is yours.

Additionally, can you write a simple example so that we can provide better documentation.

Yes, I can write a simple example. Is your proposed change above what you have finally decided to be pushed?

[luolingchun]

I still have some questions before the final decision:

1. Why use alias ( in_: str = Field(alias="in")) when you want to use by_alias=False, you can skip passing the alias parameter.
2. I don't understand the practical use of this feature, which is why I need a simple example.

[candleindark]

A good example actually exists in Pydantic's documentation (Check out https://docs.pydantic.dev/latest/usage/models/#reserved-names). In this model, if I want to use MyModel in the example as a response model and have its field named metadata in the response, I will need to generate the schema of MyModel with by_alias=False.

There are other occasions (other than the ones caused by reserved names in an ORM) in which I don't want to use the field names used in an ORM model in a response. For example, in an occasion that an ORM model is written by another development team and some field names of this model are not appropriate/informative to a user of a web API, I don't want to use those field names in my web API responses.

[luolingchun]

I drafted a PR #81 that will be merged in the next version.

[candleindark]

It looks great. Thanks a lot.