Konverter Skema OpenAPI ke Tipe TypeScript

Tempel dokumen OpenAPI 3.x (atau Swagger 2.0) dan dapatkan deklarasi interface/type TypeScript biasa untuk setiap skema di bawah components.schemas — tanpa server, tanpa CLI pembuatan kode, tanpa npm install.

Menyalin skema API secara manual ke TypeScript adalah pekerjaan membosankan dan mudah membuat kesalahan halus: setiap $ref harus dilacak kembali ke targetnya, allOf/oneOf/anyOf memerlukan bentuk union/intersection yang benar, dan field required atau nullable yang terlewatkan akan membuat tipe yang tidak jujur tentang apa yang API kembalikan. Alat ini menyelesaikan semua itu secara deterministik dari spesifikasi itu sendiri, sehingga hasilnya cocok dengan dokumen setiap kali.

Cara menggunakannya

1. Tempel dokumen OpenAPI 3.x atau Swagger 2.0 — YAML atau JSON keduanya berfungsi — ke dalam kotak input, atau klik Coba contoh untuk memuat spesifikasi Pet Store contoh.
2. Aktifkan Tambahkan komentar JSDoc dari deskripsi skema jika Anda ingin setiap interface, type, dan property diberi anotasi dengan description skemanya.
3. Salin atau unduh file .ts yang dihasilkan.

Output diperbarui secara otomatis saat Anda mengedit spesifikasi.

Apa yang dikonversi

• Resolusi $ref — setiap referensi ke components/schemas, $defs, atau (untuk Swagger 2.0) definitions diselesaikan berdasarkan nama, termasuk referensi antar skema di bucket yang berbeda. Tidak seperti konversi ke validator runtime, tipe TypeScript biasa tidak memerlukan penanganan urutan deklarasi atau siklus apa pun — interface dan type alias dapat mereferensikan satu sama lain (termasuk diri mereka sendiri) dalam urutan apa pun, jadi skema "tree node" yang mereferensikan diri hanya berfungsi.
• allOf — menjadi tipe intersection (A & B), satu anggota per entri allOf.
• oneOf / anyOf — menjadi tipe union (A | B).
• discriminator — tidak memerlukan sintaks khusus: setelah setiap anggota union adalah tipe objek dengan property literal-typed miliknya sendiri (kind: "cat" vs kind: "dog"), TypeScript sudah mempersempit union pada property tersebut. Tipe yang dihasilkan adalah union yang didiskriminasikan saat Anda beralih pada field bersama.
• nullable: true (OpenAPI 3.0) dan type: [T, "null"] (OpenAPI 3.1 / JSON Schema) — keduanya menjadi T | null.
• enum — enum string menjadi union dari literal string; const menjadi tipe literal tunggal.
• required / optional properties — kunci yang diperlukan tetap diperlukan; yang lain mendapatkan ?.
• additionalProperties — false menambahkan signature indeks [key: string]: never;; nilai skema menjadi & Record<string, T>.
• Bentuk implisit — skema yang menghilangkan type tetapi mendeklarasikan properties atau items (umum dalam spesifikasi tulisan tangan) masih dibaca sebagai objek atau array daripada jatuh kembali ke unknown.

Skema objek dipancarkan sebagai export interface; yang lainnya (union, intersection, enum, alias array, skema $ref-only) dipancarkan sebagai export type.

Bagaimana dengan parameter, request bodies, dan path?

Alat ini hanya membaca components.schemas — bentuk data yang dapat digunakan kembali. Tidak menghasilkan tipe untuk paths, parameter operasi, atau envelope respons; untuk yang tersebut, gunakan pembuat kode lengkap terhadap spesifikasi, atau tempel setiap skema yang Anda perlukan secara individual.

Spesifikasi saya menggunakan Swagger 2.0 (swagger: "2.0") — apakah ini berfungsi?

Ya, definitions dibaca dengan cara yang sama seperti components.schemas. Jika Anda lebih suka seluruh dokumen dikonversi ke OpenAPI 3.x terlebih dahulu — jalur $ref baru, requestBody, servers, dan semuanya — lihat OpenAPI v2 to v3 Converter.

Apakah spesifikasi saya divalidasi terlebih dahulu?

Tidak — alat ini mengasumsikan dokumen sudah terbentuk dengan baik dan berfokus murni pada pembuatan tipe. Jika Anda menginginkan validasi struktural (missing operationId, $ref yang tidak dapat diselesaikan, parameter path yang tidak dideklarasikan) sebelum atau bukan mengonversi, lihat OpenAPI / Swagger Validator.

Saya membutuhkan skema Zod, bukan tipe TypeScript biasa

Lihat JSON Schema to Zod Schema Converter — tempel satu skema (bukan dokumen OpenAPI lengkap) untuk mendapatkan skema Zod validasi runtime ditambah tipe TypeScript yang disimpulkan.

Apakah spesifikasi saya dikirim ke mana pun?

Tidak. Penguraian dan pembuatan tipe berjalan sepenuhnya di browser Anda — kode yang sama yang berjalan di sini juga mendukung API publik dan alat MCP, dan tidak ada yang membuat permintaan jaringan.