如何在FastAPI文档中隐藏Pydantic模型的用户无需提交的ID字段

针对你遇到的问题，推荐两种更优的解决方案，既能避免可选字段的模糊性，也能减少重复模型的冗余：

方案1：模型继承（最清晰易维护） #

通过基础模型提取公共字段，再分别定义请求、返回专用模型，既无代码重复，又能明确区分不同场景的字段要求：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 基础模型：存放Item的所有公共字段
class BaseItem(BaseModel):
    name: str

# 请求用模型：仅包含用户需提交的字段（不含id）
class CreateItem(BaseItem):
    pass

# 返回用模型：包含数据库自动生成的id字段
class Item(BaseItem):
    id: int

@app.post("/item/create", status_code=201, tags=["Item"], response_model=Item)
def create_item(item: CreateItem):
    # 模拟数据库创建条目并生成id
    created_item = {"id": 1, "name": item.name}
    return created_item

• 优势：代码结构清晰，请求文档仅展示name字段，返回文档包含id和name，完全匹配业务逻辑；后续字段变更只需修改基础模型，维护成本低。

方案2：用Pydantic的SkipJsonSchema隐藏字段（Pydantic v2+） #

如果不想拆分模型，可以通过Annotated结合SkipJsonSchema让id字段不显示在API文档中，但保留模型内的字段定义：

from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import Annotated
from pydantic_core import core_schema

# 自定义注解：标记字段跳过JSON Schema生成
def SkipJsonSchema():
    def validator(v):
        return v
    return core_schema.no_info_before_validator_function(
        validator,
        json_schema=core_schema.null_schema(),
    )

app = FastAPI()

class Item(BaseModel):
    # 标记id字段不展示在API文档中
    id: Annotated[int, SkipJsonSchema()] = Field(default=None)
    name: str

@app.post("/item/create", status_code=201, tags=["Item"], response_model=Item)
def create_item(item: Item):
    # 忽略用户提交的id，使用数据库生成的id
    created_item = Item(id=1, name=item.name)
    return created_item

• 注意：此方法要求Pydantic版本为v2及以上，且必须在业务逻辑中忽略用户提交的id值，避免安全风险。

两种方案中，模型继承的方式更符合代码规范和业务逻辑的清晰性，是优先推荐的选择。

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