粘贴用 Pydantic BaseModel、@dataclass 或 TypedDict 编写的 Python 模型,就能得到遵循其结构的示例 JSON 文档。Field(alias=...) 和 alias_generator=to_camel 配置都会被读取,所以你能看到 snake_case 字段实际序列化成的 key。
适合为 FastAPI 接口构造请求示例、与其他团队共享 webhook 或队列 payload 的结构,或者为 pytest 准备 JSON fixture。
.py 文件内容。import 行、方法以及 @field_validator 等装饰器会被跳过。Enum 类也放进来,这些部分才会被填充。字符串形式的前向引用("Order")也能理解。自动 时,根类型 会选出没有被其他模型用作字段类型的类;也可以从列表中选择。json_schema_extra 的 examples、测试数据文件或 API 文档中。class Payer(BaseModel):
model_config = ConfigDict(alias_generator=to_camel)
customer_id: str
email_address: str
class PaymentEvent(BaseModel):
model_config = ConfigDict(alias_generator=to_camel)
event_type: Literal["payment.succeeded", "payment.failed"]
amount: Decimal
currency: str = "KRW"
payer: Payer
receipt_url: Optional[str] = None
retry_count: int = Field(default=0, alias="retries")
raw_payload: dict = Field(exclude=True){
"eventType": "payment.succeeded",
"amount": "0",
"currency": "KRW",
"payer": {
"customerId": "",
"emailAddress": ""
},
"receiptUrl": "",
"retries": 0
}由于 model_config 中的 to_camel,event_type、receipt_url 和 customer_id 变成了 camelCase key,而 retry_count 则以显式的 alias="retries" 为准。raw_payload 带有 Field(exclude=True),被省略。Literal 取第一个值 payment.succeeded,字面量默认值 "KRW" 保持原样。
BaseModel(v1 和 v2)、@dataclass、TypedDict,以及包括 auto() 在内的 Enum/StrEnum/IntEnum。Field(alias=...)、serialization_alias,以及在 model_config = ConfigDict(...) 或内部 class Config: 中设置的 alias_generator(to_camel、to_pascal)。_ 开头的名称、ClassVar、model_config 以及 Field(exclude=True) 字段。Optional[X] / X | None → X 的示例,Literal[...] → 第一个值,Annotated/Required/NotRequired → 内部类型,list/set/tuple → 单元素数组,dict[str, V] → {"key": V}。EmailStr、HttpUrl、SecretStr、constr → 字符串;conint、PositiveInt → 0;Decimal 和 condecimal → 字符串 "0",与 Pydantic v2 JSON 的输出一致。datetime → 1970-01-01T00:00:00,date → 1970-01-01,time → 00:00:00,timedelta → PT0S;UUID 会得到格式正确的值。True/False 字面量形式的默认值会用作示例;Status.PAID 这样的 enum 默认值会变成该成员的值。根据请求模型生成 JSON,放进 model_config = {"json_schema_extra": {"examples": [...]}};这样 /docs 上的示例就会使用接口所期望的同一套别名 key。
如果 Celery 任务或 Kafka 消息的 payload 是用 Pydantic 定义的,交给使用 Node 或 Go 的消费方团队生成的 JSON 而不是 Python 代码,以此约定结构。
为 model_validate_json() 或 API 客户端测试生成 JSON 文件的骨架,再修改个别值来加入边界情况。
Optional 字段和默认值为 None 的字段,仍然会得到按类型生成的示例而不是 null。Decimal 填充为字符串 "0",与 Pydantic v2 的 JSON 序列化(model_dump_json)一致。如果项目输出的是数字(Pydantic v1,或 json.dumps(default=float)),请改成数字。@computed_field、@field_serializer 或 @model_serializer 等改变输出形态的代码不会被执行。Union[A, B] 使用第一个非 None 的成员;不会模拟通过 discriminator 字段选择的可辨识联合。default_factory 以及由函数调用产生的默认值不会被执行,值由类型决定。model_dump_json() 打印的是字段名。除非传入 by_alias=True,Pydantic 都按字段名序列化。FastAPI 的 response_model 默认使用 by_alias=True,与本工具的输出一致。自己 dump 时请调用 model_dump_json(by_alias=True)。
标准的 dataclass 没有重命名功能,所以字段名就是 key。如果字段末尾带有 # JSON: "orderId" 注释(就像本站 JSON → Python 页面生成的 dataclass 那样),则使用该名称。
TypedDict 中 NotRequired 的 key 会包含在内吗?会。示例旨在展示所有可能的 key,所以 NotRequired 和 total=False 的字段都会包含。请在文档中标明哪些可以省略。
本页面向基于类型提示的模型。用 Column(...) 或 Mapped[...] 声明的 SQLAlchemy 模型,请使用 SQLAlchemy → JSON 页面。