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.
.py chứa model. Các dòng import, method và decorator như @field_validator được bỏ qua.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.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.examples của json_schema_extra, file dữ liệu test hoặc tài liệu 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
}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.
BaseModel của Pydantic (v1 và v2), @dataclass, TypedDict, và Enum/StrEnum/IntEnum kể cả auto().Field(alias=...), serialization_alias, và alias_generator (to_camel, to_pascal) đặt trong model_config = ConfigDict(...) hoặc class Config: bên trong._, ClassVar, model_config, và field có Field(exclude=True).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}.EmailStr, HttpUrl, SecretStr, constr → chuỗi; conint, PositiveInt → 0; Decimal và condecimal → chuỗi "0", đúng như JSON của Pydantic v2 ghi ra.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.True/False được dùng làm mẫu; mặc định enum như Status.PAID thành giá trị của member đó.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.
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.
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.
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ố.@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.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 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.
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.
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.