วางโมเดล Python ที่เขียนด้วย BaseModel ของ Pydantic, @dataclass หรือ TypedDict แล้วจะได้ JSON ตัวอย่างตามโครงสร้างของมัน เครื่องมืออ่าน Field(alias=...) และคอนฟิก alias_generator=to_camel ด้วย จึงเห็นคีย์ที่ฟิลด์แบบ snake_case ถูก serialize ออกไปจริง
เหมาะกับการสร้างตัวอย่าง request ของ endpoint ใน FastAPI การแชร์ schema ของ payload ใน webhook หรือคิวให้ทีมอื่น หรือการเตรียม JSON fixture สำหรับ pytest
.py ที่มีโมเดล บรรทัด import เมธอด และ decorator อย่าง @field_validator จะถูกข้ามEnum ที่ถูกอ้างถึงไว้ด้วย เพื่อให้ส่วนนั้นถูกเติมค่า forward reference แบบสตริง ("Order") ก็เข้าใจได้อัตโนมัติ ชนิดราก จะเลือกคลาสที่ไม่ถูกโมเดลอื่นใช้เป็นไทป์ของฟิลด์ หรือจะเลือกจากรายการก็ได้examples ของ json_schema_extra ไฟล์ข้อมูลทดสอบ หรือเอกสาร APIclass 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
}เพราะ to_camel ใน model_config ทำให้ event_type, receipt_url และ customer_id กลายเป็นคีย์แบบ camelCase ขณะที่ alias="retries" ที่ระบุชัดเจนมีผลเหนือกว่าสำหรับ retry_count raw_payload มี Field(exclude=True) จึงถูกตัดออก Literal ใช้ค่าแรกคือ payment.succeeded และค่าเริ่มต้น literal "KRW" ถูกเก็บไว้ตามเดิม
BaseModel ของ Pydantic (v1 และ v2), @dataclass, TypedDict และ Enum/StrEnum/IntEnum รวมถึง auto()Field(alias=...), serialization_alias และ alias_generator (to_camel, to_pascal) ที่ตั้งใน model_config = ConfigDict(...) หรือ class Config: ข้างใน_, 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" ตามที่ JSON ของ Pydantic v2 เขียนออกมาdatetime → 1970-01-01T00:00:00, date → 1970-01-01, time → 00:00:00, timedelta → PT0S และ UUID ได้ค่าที่รูปแบบถูกต้องTrue/False ถูกใช้เป็นตัวอย่าง ค่าเริ่มต้นที่เป็น enum อย่าง Status.PAID จะกลายเป็นค่าของสมาชิกนั้นสร้าง JSON จากโมเดลของ request แล้วใส่ลงใน model_config = {"json_schema_extra": {"examples": [...]}} ตัวอย่างใน /docs จะใช้คีย์ alias เดียวกับที่ endpoint คาดหวัง
ถ้า payload ของ task ใน Celery หรือข้อความใน Kafka นิยามด้วย Pydantic ให้ส่ง JSON ที่ได้ให้ทีม consumer ที่ใช้ Node หรือ Go แทนโค้ด Python เพื่อตกลงโครงสร้างกัน
สร้างโครงไฟล์ JSON สำหรับ model_validate_json() หรือเทสต์ของ API client แล้วเปลี่ยนค่าบางตัวเพื่อเพิ่ม edge case
Optional และฟิลด์ที่ค่าเริ่มต้นเป็น None ยังได้ค่าตัวอย่างตามไทป์แทน nullDecimal ถูกเติมเป็นสตริง "0" ตรงกับการ serialize JSON ของ Pydantic v2 (model_dump_json) ถ้าโปรเจกต์ของคุณส่งออกเป็นตัวเลข (Pydantic v1 หรือ json.dumps(default=float)) ให้เปลี่ยนเป็นตัวเลข@computed_field, @field_serializer หรือ @model_serializer ไม่ถูกรันUnion[A, B] ใช้สมาชิกตัวแรกที่ไม่ใช่ None และไม่จำลอง discriminated union ที่เลือกด้วยฟิลด์ discriminatordefault_factory และค่าเริ่มต้นที่ได้จากการเรียกฟังก์ชันไม่ถูกรัน ค่าจะมาจากไทป์model_dump_json() ของฉันพิมพ์ชื่อฟิลด์ออกมาPydantic serialize ด้วยชื่อฟิลด์เว้นแต่จะส่ง by_alias=True response_model ของ FastAPI ใช้ by_alias=True เป็นค่าเริ่มต้น ซึ่งตรงกับผลลัพธ์ของเครื่องมือนี้ ถ้า dump เอง ให้เรียก model_dump_json(by_alias=True)
dataclass มาตรฐานไม่มีการเปลี่ยนชื่อ ชื่อฟิลด์จึงเป็นคีย์ ถ้าฟิลด์มีคอมเมนต์ # JSON: "orderId" ต่อท้าย แบบใน dataclass ที่สร้างจากหน้า JSON → Python ของเว็บนี้ จะใช้ชื่อนั้น
NotRequired ของ TypedDict ถูกรวมไว้ไหม?รวม ตัวอย่างตั้งใจแสดงทุกคีย์ที่เป็นไปได้ ฟิลด์ NotRequired และ total=False จึงอยู่ด้วย ให้ระบุในเอกสารว่าตัวไหนอาจไม่ถูกส่งมา
หน้านี้สำหรับโมเดลที่อิง type hint สำหรับโมเดล SQLAlchemy ที่ประกาศด้วย Column(...) หรือ Mapped[...] ให้ใช้หน้า SQLAlchemy → JSON