将 Python 类转换为 JSON!

粘贴 Python Pydantic·dataclass 代码即可生成示例 JSON!支持 Pydantic BaseModel, Field(alias), dataclass, TypedDict。适用于 API 文档和测试请求体(sample JSON)。
Python
结果
 

将 Python 类转换为 JSON!

粘贴用 Pydantic BaseModel、@dataclass 或 TypedDict 编写的 Python 模型,就能得到遵循其结构的示例 JSON 文档。Field(alias=...) 和 alias_generator=to_camel 配置都会被读取,所以你能看到 snake_case 字段实际序列化成的 key。

适合为 FastAPI 接口构造请求示例、与其他团队共享 webhook 或队列 payload 的结构,或者为 pytest 准备 JSON fixture。

使用方法

  1. 粘贴存放模型的 .py 文件内容。import 行、方法以及 @field_validator 等装饰器会被跳过。
  2. 把引用到的子模型和 Enum 类也放进来,这些部分才会被填充。字符串形式的前向引用("Order")也能理解。
  3. 设为 自动 时,根类型 会选出没有被其他模型用作字段类型的类;也可以从列表中选择。
  4. 把 JSON 复制到 json_schema_extra 的 examples、测试数据文件或 API 文档中。

示例

输入 (Python · Pydantic)
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)
输出 (JSON)
{
  "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" 保持原样。

支持的功能

  • 读取 Pydantic BaseModel(v1 和 v2)、@dataclass、TypedDict,以及包括 auto() 在内的 Enum/StrEnum/IntEnum。
  • key 名来自 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}。
  • Pydantic 类型: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 默认值会变成该成员的值。

使用场景

FastAPI 请求示例

根据请求模型生成 JSON,放进 model_config = {"json_schema_extra": {"examples": [...]}};这样 /docs 上的示例就会使用接口所期望的同一套别名 key。

共享 webhook 和事件 payload

如果 Celery 任务或 Kafka 消息的 payload 是用 Pydantic 定义的,交给使用 Node 或 Go 的消费方团队生成的 JSON 而不是 Python 代码,以此约定结构。

准备 pytest fixture

为 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 以及由函数调用产生的默认值不会被执行,值由类型决定。

常见问题

输出使用的是别名 key,但我的 model_dump_json() 打印的是字段名。

除非传入 by_alias=True,Pydantic 都按字段名序列化。FastAPI 的 response_model 默认使用 by_alias=True,与本工具的输出一致。自己 dump 时请调用 model_dump_json(by_alias=True)。

dataclass 没有别名,key 还会与字段名不同吗?

标准的 dataclass 没有重命名功能,所以字段名就是 key。如果字段末尾带有 # JSON: "orderId" 注释(就像本站 JSON → Python 页面生成的 dataclass 那样),则使用该名称。

TypedDict 中 NotRequired 的 key 会包含在内吗?

会。示例旨在展示所有可能的 key,所以 NotRequired 和 total=False 的字段都会包含。请在文档中标明哪些可以省略。

能处理 SQLAlchemy 模型吗?

本页面向基于类型提示的模型。用 Column(...) 或 Mapped[...] 声明的 SQLAlchemy 模型,请使用 SQLAlchemy → JSON 页面。