แปลงคลาส Python เป็น JSON!

วางโค้ด Python (Pydantic·dataclass) แล้วรับ JSON ตัวอย่าง! รองรับ Pydantic BaseModel, Field(alias), dataclass, TypedDict เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
Python
ผลลัพธ์
 

แปลงคลาส Python เป็น JSON!

วางโมเดล Python ที่เขียนด้วย BaseModel ของ Pydantic, @dataclass หรือ TypedDict แล้วจะได้ JSON ตัวอย่างตามโครงสร้างของมัน เครื่องมืออ่าน Field(alias=...) และคอนฟิก alias_generator=to_camel ด้วย จึงเห็นคีย์ที่ฟิลด์แบบ snake_case ถูก serialize ออกไปจริง

เหมาะกับการสร้างตัวอย่าง request ของ endpoint ใน FastAPI การแชร์ schema ของ payload ใน webhook หรือคิวให้ทีมอื่น หรือการเตรียม JSON fixture สำหรับ pytest

วิธีใช้

  1. วางเนื้อหาของไฟล์ .py ที่มีโมเดล บรรทัด import เมธอด และ decorator อย่าง @field_validator จะถูกข้าม
  2. ใส่ sub-model และคลาส Enum ที่ถูกอ้างถึงไว้ด้วย เพื่อให้ส่วนนั้นถูกเติมค่า forward reference แบบสตริง ("Order") ก็เข้าใจได้
  3. เมื่อเป็น อัตโนมัติ ชนิดราก จะเลือกคลาสที่ไม่ถูกโมเดลอื่นใช้เป็นไทป์ของฟิลด์ หรือจะเลือกจากรายการก็ได้
  4. คัดลอก JSON ไปใส่ examples ของ json_schema_extra ไฟล์ข้อมูลทดสอบ หรือเอกสาร 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
}

เพราะ 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}
  • ไทป์ของ Pydantic: 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 ได้ค่าที่รูปแบบถูกต้อง
  • ค่าเริ่มต้นที่เป็น literal ของสตริง ตัวเลข และ True/False ถูกใช้เป็นตัวอย่าง ค่าเริ่มต้นที่เป็น enum อย่าง Status.PAID จะกลายเป็นค่าของสมาชิกนั้น

กรณีการใช้งาน

ตัวอย่าง request ของ FastAPI

สร้าง JSON จากโมเดลของ request แล้วใส่ลงใน model_config = {"json_schema_extra": {"examples": [...]}} ตัวอย่างใน /docs จะใช้คีย์ alias เดียวกับที่ endpoint คาดหวัง

แชร์ payload ของ webhook และ event

ถ้า payload ของ task ใน Celery หรือข้อความใน Kafka นิยามด้วย Pydantic ให้ส่ง JSON ที่ได้ให้ทีม consumer ที่ใช้ Node หรือ Go แทนโค้ด Python เพื่อตกลงโครงสร้างกัน

เตรียม fixture ของ pytest

สร้างโครงไฟล์ JSON สำหรับ model_validate_json() หรือเทสต์ของ API client แล้วเปลี่ยนค่าบางตัวเพื่อเพิ่ม edge case

ข้อควรระวังและข้อจำกัด

  • ฟิลด์ Optional และฟิลด์ที่ค่าเริ่มต้นเป็น None ยังได้ค่าตัวอย่างตามไทป์แทน null
  • Decimal ถูกเติมเป็นสตริง "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 ที่เลือกด้วยฟิลด์ discriminator
  • default_factory และค่าเริ่มต้นที่ได้จากการเรียกฟังก์ชันไม่ถูกรัน ค่าจะมาจากไทป์

คำถามที่พบบ่อย

ผลลัพธ์ใช้คีย์ alias แต่ model_dump_json() ของฉันพิมพ์ชื่อฟิลด์ออกมา

Pydantic serialize ด้วยชื่อฟิลด์เว้นแต่จะส่ง by_alias=True response_model ของ FastAPI ใช้ by_alias=True เป็นค่าเริ่มต้น ซึ่งตรงกับผลลัพธ์ของเครื่องมือนี้ ถ้า dump เอง ให้เรียก model_dump_json(by_alias=True)

dataclass ไม่มี alias คีย์จะต่างจากชื่อฟิลด์ได้ไหม?

dataclass มาตรฐานไม่มีการเปลี่ยนชื่อ ชื่อฟิลด์จึงเป็นคีย์ ถ้าฟิลด์มีคอมเมนต์ # JSON: "orderId" ต่อท้าย แบบใน dataclass ที่สร้างจากหน้า JSON → Python ของเว็บนี้ จะใช้ชื่อนั้น

คีย์ NotRequired ของ TypedDict ถูกรวมไว้ไหม?

รวม ตัวอย่างตั้งใจแสดงทุกคีย์ที่เป็นไปได้ ฟิลด์ NotRequired และ total=False จึงอยู่ด้วย ให้ระบุในเอกสารว่าตัวไหนอาจไม่ถูกส่งมา

รองรับโมเดล SQLAlchemy ไหม?

หน้านี้สำหรับโมเดลที่อิง type hint สำหรับโมเดล SQLAlchemy ที่ประกาศด้วย Column(...) หรือ Mapped[...] ให้ใช้หน้า SQLAlchemy → JSON