Tukar kelas Python kepada JSON!

Tampal kod Python (Pydantic·dataclass) dan dapatkan contoh JSON! Menyokong Pydantic BaseModel, Field(alias), dataclass, TypedDict. Berguna untuk dokumentasi API dan badan permintaan ujian (mock request body).
Python
Hasil
 

Tukar kelas Python kepada JSON!

Tampal model Python yang ditulis dengan Pydantic BaseModel, @dataclass atau TypedDict, dan dapatkan contoh dokumen JSON yang mengikut strukturnya. Field(alias=...) dan konfigurasi alias_generator=to_camel turut dibaca, jadi anda nampak kunci sebenar yang dihasilkan apabila medan snake_case anda diserialkan.

Ia sesuai untuk membina contoh request bagi endpoint FastAPI, berkongsi skema payload webhook atau queue dengan pasukan lain, atau menyediakan fixture JSON untuk pytest.

Cara menggunakan

  1. Tampal kandungan fail .py yang memuatkan model anda. Baris import, method dan decorator seperti @field_validator dilangkau.
  2. Sertakan sub-model dan kelas Enum yang dirujuk supaya bahagian tersebut diisi. Forward reference berbentuk rentetan ("Order") difahami.
  3. Pada Automatik, Jenis akar memilih kelas yang tidak digunakan sebagai jenis medan oleh model lain; anda juga boleh memilih satu daripada senarai.
  4. Salin JSON ke dalam examples json_schema_extra, fail data ujian atau dokumentasi API anda.

Contoh

Input (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)
Output (JSON)
{
  "eventType": "payment.succeeded",
  "amount": "0",
  "currency": "KRW",
  "payer": {
    "customerId": "",
    "emailAddress": ""
  },
  "receiptUrl": "",
  "retries": 0
}

Disebabkan to_camel dalam model_config, event_type, receipt_url dan customer_id bertukar menjadi kunci camelCase, manakala alias="retries" yang eksplisit diutamakan bagi retry_count. raw_payload mempunyai Field(exclude=True) dan ditinggalkan. Literal mengambil nilai pertamanya, payment.succeeded, dan default literal "KRW" dikekalkan seadanya.

Ciri yang disokong

  • Membaca Pydantic BaseModel (v1 dan v2), @dataclass, TypedDict, dan Enum/StrEnum/IntEnum termasuk auto().
  • Nama kunci daripada Field(alias=...), serialization_alias, dan alias_generator (to_camel, to_pascal) yang ditetapkan dalam model_config = ConfigDict(...) atau class Config: dalaman.
  • Dikecualikan: nama yang bermula dengan _, ClassVar, model_config, dan medan Field(exclude=True).
  • Pengendalian jenis: Optional[X] / X | None → contoh X, Literal[...] → nilai pertama, Annotated/Required/NotRequired → jenis dalaman, list/set/tuple → array satu elemen, dict[str, V] → {"key": V}.
  • Jenis Pydantic: EmailStr, HttpUrl, SecretStr, constr → rentetan; conint, PositiveInt → 0; Decimal dan condecimal → rentetan "0", sebagaimana JSON Pydantic v2 menulisnya.
  • Tarikh dan masa: datetime → 1970-01-01T00:00:00, date → 1970-01-01, time → 00:00:00, timedelta → PT0S; UUID mendapat nilai yang berformat sah.
  • Default literal rentetan, nombor dan True/False digunakan sebagai contoh; default enum seperti Status.PAID menjadi nilai ahli tersebut.

Kes penggunaan

Contoh request FastAPI

Jana JSON daripada model request dan masukkan ke dalam model_config = {"json_schema_extra": {"examples": [...]}}; contoh di /docs kemudian menggunakan kunci alias yang sama seperti yang dijangka oleh endpoint.

Berkongsi payload webhook dan event

Jika payload tugas Celery atau mesej Kafka ditakrifkan dalam Pydantic, berikan JSON yang terhasil kepada pasukan consumer yang menggunakan Node atau Go, bukannya kod Python, untuk bersetuju tentang struktur.

Menyediakan fixture pytest

Cipta rangka fail JSON untuk model_validate_json() atau ujian klien API, kemudian ubah nilai satu per satu untuk menambah kes tepi.

Nota dan had

  • Medan Optional dan medan yang default kepada None tetap mendapat contoh mengikut jenis, bukannya null.
  • Decimal diisi sebagai rentetan "0", sepadan dengan serialisasi JSON Pydantic v2 (model_dump_json). Jika projek anda mengeluarkan nombor (Pydantic v1, atau json.dumps(default=float)), tukarkannya kepada nombor.
  • Kod yang mengubah bentuk output, seperti @computed_field, @field_serializer atau @model_serializer, tidak dijalankan.
  • Union[A, B] menggunakan ahli pertama yang bukan None; discriminated union yang dipilih melalui medan discriminator tidak dimodelkan.
  • default_factory dan default yang dihasilkan oleh panggilan fungsi tidak dijalankan; nilainya diambil daripada jenis.

Soalan lazim

Output menggunakan kunci alias, tetapi model_dump_json() saya mencetak nama medan.

Pydantic menserialkan mengikut nama medan kecuali anda menghantar by_alias=True. response_model FastAPI menggunakan by_alias=True secara lalai, yang sepadan dengan output alat ini. Apabila membuat dump sendiri, panggil model_dump_json(by_alias=True).

Dataclass tiada alias. Bolehkah kunci masih berbeza daripada nama medan?

dataclass standard tidak menyokong penamaan semula, jadi nama medan ialah kuncinya. Jika sesuatu medan mempunyai komen # JSON: "orderId" di hujung baris, seperti dalam dataclass yang dihasilkan oleh halaman JSON → Python di laman ini, nama tersebut digunakan.

Adakah kunci NotRequired dalam TypedDict disertakan?

Ya. Contoh ini bertujuan menunjukkan setiap kunci yang mungkin, jadi medan NotRequired dan total=False disertakan. Tandakan yang boleh ditinggalkan dalam dokumentasi anda.

Adakah ia mengendalikan model SQLAlchemy?

Halaman ini untuk model berasaskan type hint. Bagi model SQLAlchemy yang diisytiharkan dengan Column(...) atau Mapped[...], gunakan halaman SQLAlchemy → JSON.