FastAPI中如何让Pydantic模型的property纳入JSON响应并生成文档

要让Pydantic模型的计算字段同时出现在JSON响应和OpenAPI文档中，最优雅的方式是使用Pydantic v2提供的ComputedField装饰器（若仍在使用v1，后面会补充兼容方案）。

修改后的代码 #

import uvicorn
from fastapi import FastAPI
from pydantic import Field, BaseModel, ComputedField

app = FastAPI()


class Item(BaseModel):
    id: str = Field(description="Item ID")

    model_config = {
        "json_schema_extra": {
            "examples": [{"id": "my_name", "name": "My Name"}]
        }
    }

    @ComputedField(description="自动生成的Item名称")
    def name(self) -> str:
        return self.id.replace("_", " ").upper()


@app.get("/")
async def main() -> Item:
    return Item(id="my_name")


if __name__ == "__main__":
    uvicorn.run(app)

效果说明 #

• @ComputedField会标记该属性为计算字段，自动将其纳入JSON序列化输出，访问http://127.0.0.1:8000/会返回预期的{"id": "my_name", "name": "MY NAME"}。
• 该装饰器会自动把字段信息同步到OpenAPI Schema中，在/docs页面能看到name字段的类型、描述，与示例数据匹配。

Pydantic v1兼容方案 #

若未升级到v2，可通过手动补充序列化逻辑和Schema信息实现：

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel, Field, PrivateAttr

app = FastAPI()


class Item(BaseModel):
    id: str = Field(description="Item ID")
    _name: str = PrivateAttr(default=None)

    model_config = {
        "json_schema_extra": {
            "examples": [{"id": "my_name", "name": "My Name"}],
            "properties": {"name": {"type": "string", "description": "自动生成的Item名称"}}
        }
    }

    @property
    def name(self) -> str:
        if not self._name:
            self._name = self.id.replace("_", " ").upper()
        return self._name

    def dict(self, **kwargs):
        data = super().dict(**kwargs)
        data["name"] = self.name
        return data


@app.get("/")
async def main() -> Item:
    return Item(id="my_name")


if __name__ == "__main__":
    uvicorn.run(app)

此方案通过重写dict()方法将计算字段加入序列化结果，同时在json_schema_extra中补充字段Schema，确保/docs页面能正确展示该字段。

内容的提问来源于stack exchange，提问作者pyjedy