Chuyển class Python sang JSON!

Dán mã Python (Pydantic·dataclass) để nhận JSON mẫu! Hỗ trợ Pydantic BaseModel, Field(alias), dataclass, TypedDict. Hữu ích cho tài liệu API và request body thử nghiệm (mock request body).
Python
Kết quả
 

Chuyển class Python sang JSON!

Dán model Python viết bằng BaseModel của Pydantic, @dataclass hoặc TypedDict, và nhận lại một tài liệu JSON mẫu theo đúng cấu trúc của chúng. Field(alias=...) và cấu hình alias_generator=to_camel đều được đọc, nên bạn thấy được key mà các field snake_case thực sự serialize ra.

Nó phù hợp để tạo ví dụ request cho endpoint FastAPI, chia sẻ schema payload của webhook hay hàng đợi với đội khác, hoặc chuẩn bị JSON fixture cho pytest.

Cách sử dụng

  1. Dán nội dung file .py chứa model. Các dòng import, method và decorator như @field_validator được bỏ qua.
  2. Đưa vào cả các sub-model và class Enum được tham chiếu để những phần đó được điền giá trị. Forward reference dạng chuỗi ("Order") cũng được hiểu.
  3. Khi để Tự động, Kiểu gốc chọn class không được model khác dùng làm kiểu field; bạn cũng có thể chọn một class trong danh sách.
  4. Sao chép JSON vào examples của json_schema_extra, file dữ liệu test hoặc tài liệu API.

Ví dụ

Đầu vào (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)
Đầu ra (JSON)
{
  "eventType": "payment.succeeded",
  "amount": "0",
  "currency": "KRW",
  "payer": {
    "customerId": "",
    "emailAddress": ""
  },
  "receiptUrl": "",
  "retries": 0
}

Nhờ to_camel trong model_config, event_type, receipt_url và customer_id thành key camelCase, còn alias="retries" tường minh được ưu tiên cho retry_count. raw_payload có Field(exclude=True) nên bị bỏ. Literal lấy giá trị đầu tiên, payment.succeeded, và mặc định dạng literal "KRW" được giữ nguyên.

Tính năng hỗ trợ

  • Đọc BaseModel của Pydantic (v1 và v2), @dataclass, TypedDict, và Enum/StrEnum/IntEnum kể cả auto().
  • Tên key từ Field(alias=...), serialization_alias, và alias_generator (to_camel, to_pascal) đặt trong model_config = ConfigDict(...) hoặc class Config: bên trong.
  • Bị loại: tên bắt đầu bằng _, ClassVar, model_config, và field có Field(exclude=True).
  • Xử lý kiểu: Optional[X] / X | None → mẫu của X, Literal[...] → giá trị đầu tiên, Annotated/Required/NotRequired → kiểu bên trong, list/set/tuple → mảng một phần tử, dict[str, V] → {"key": V}.
  • Kiểu của Pydantic: EmailStr, HttpUrl, SecretStr, constr → chuỗi; conint, PositiveInt → 0; Decimal và condecimal → chuỗi "0", đúng như JSON của Pydantic v2 ghi ra.
  • Ngày và giờ: datetime → 1970-01-01T00:00:00, date → 1970-01-01, time → 00:00:00, timedelta → PT0S; UUID nhận giá trị đúng định dạng.
  • Mặc định dạng literal chuỗi, số và True/False được dùng làm mẫu; mặc định enum như Status.PAID thành giá trị của member đó.

Trường hợp sử dụng

Ví dụ request cho FastAPI

Tạo JSON từ model request rồi đặt vào model_config = {"json_schema_extra": {"examples": [...]}}; ví dụ trên /docs khi đó dùng đúng các key alias mà endpoint mong đợi.

Chia sẻ payload webhook và event

Nếu payload của task Celery hay message Kafka được định nghĩa bằng Pydantic, hãy đưa cho đội consumer dùng Node hay Go JSON kết quả thay vì code Python để thống nhất cấu trúc.

Chuẩn bị fixture cho pytest

Tạo khung file JSON cho model_validate_json() hoặc test API client, rồi đổi từng giá trị để thêm các trường hợp biên.

Lưu ý và giới hạn

  • Field Optional và field mặc định None vẫn nhận giá trị mẫu theo kiểu thay vì null.
  • Decimal được điền bằng chuỗi "0", khớp với cách serialize JSON của Pydantic v2 (model_dump_json). Nếu dự án của bạn xuất ra số (Pydantic v1, hoặc json.dumps(default=float)), hãy đổi thành số.
  • Code thay đổi hình dạng output, như @computed_field, @field_serializer hay @model_serializer, không được thực thi.
  • Union[A, B] dùng thành viên đầu tiên không phải None; discriminated union được chọn theo field discriminator không được mô phỏng.
  • default_factory và mặc định tạo từ lời gọi hàm không được chạy; giá trị lấy theo kiểu.

Câu hỏi thường gặp

Output dùng key alias, nhưng model_dump_json() của tôi lại in tên field.

Pydantic serialize theo tên field trừ khi bạn truyền by_alias=True. response_model của FastAPI mặc định dùng by_alias=True, khớp với output của công cụ này. Khi tự dump, hãy gọi model_dump_json(by_alias=True).

Dataclass không có alias. Key có thể khác tên field không?

dataclass chuẩn không có cơ chế đổi tên, nên tên field chính là key. Nếu field có comment # JSON: "orderId" ở cuối, như dataclass do trang JSON → Python của trang này tạo ra, tên đó sẽ được dùng.

Key NotRequired của TypedDict có được đưa vào không?

Có. Mẫu nhằm cho thấy mọi key có thể có, nên field NotRequired và total=False đều được đưa vào. Hãy đánh dấu trong tài liệu những key có thể bị bỏ qua.

Có xử lý model SQLAlchemy không?

Trang này dành cho model dựa trên type hint. Với model SQLAlchemy khai báo bằng Column(...) hoặc Mapped[...], hãy dùng trang SQLAlchemy → JSON.