OpenAPI TypeScript: Buat Tipe, Klien, dan Validasi

Anda biasanya dapat menemukan saat API pipeline mulai berbohong kepada tim. Sebuah schema berubah, tipe yang dihasilkan diperbarui tanpa keluhan, PR berwarna hijau, dan kemudian seseorang di frontend terus membaca bentuk respons lama karena wrapper menutupi kesalahan. Itu adalah masalah OpenAPI TypeScript, bukan apakah generator dapat mengeluarkan interface.

Pertanyaan yang berguna lebih sulit. Apa kontrak yang Anda inginkan antara schema, transportasi, dan validasi, dan bagian mana yang harus gagal cepat pada waktu build daripada bocor ke waktu eksekusi? Setelah Anda menggambarkan OpenAPI TypeScript sebagai pilihan pipa, kekurangan menjadi lebih jelas, dan alat-alat berhenti berpura-pura menjadi solusi keseluruhan.

Daftar Isi

• Alasan Tipe yang Dibuat Tidak Sama dengan API yang Aman
  • Dimana Kegagalan Tersembunyi
• Menghasilkan Tipe TypeScript dari Spec OpenAPI
  • Bendera yang Benar-Benar Penting
• Memilih Antara Tipe Murni, Klien Penuh, dan Tidak Menggunakan Pengkodean
  • Tipe Murni Memprioritaskan Kontrol
  • Klien Penuh Memprioritaskan Kecepatan Pengiriman
  • Tidak Menggunakan Pengkodean Memprioritaskan Refaktor Lokal
• Menghubungkan Klien Tipis yang Dibungkus dengan Fetch atau Axios
• Menambahkan Validasi Waktu Eksekusi dengan zod, ajv, atau io-ts
  • Memeriksa di mana data masuk
• Membuat Pengujian Penerbitan, Pengujian Validasi, dan Pengujian Kontrak di CI
  • Gaya Aksi Sederhana GitHub
• Alur Pipa yang Dapat Diperbarui, Kinerja, dan Daftar Periksa Akhir
  • Beberapa Pengaturan Kinerja yang Sebenarnya Berpengaruh

Mengapa Tipe-Tipe yang Dibuat Tidak Sama dengan API yang Aman

Seorang rekan tim menggabungkan PR yang menambahkan bidang respons opsional. File yang dibuat secara otomatis diperbarui dengan bersih, perbedaan tampaknya membosankan, dan semua orang melanjutkan. Kemudian frontend terus membaca bentuk yang lebih tua melalui wrapper yang ditulis tangan yang "sementara" diberi tanda dengan as anydan produksi mulai berperilaku seperti kontrak tidak pernah berubah.

Itu adalah perangkap dengan tipe-tipe yang dibuat. TypeScript hanya dapat melindungi code yang mengonsumsi tipe-tipe yang dibuatdan hanya jika lapisan transportasi tidak menghapus kontrak lagi. Sisi OpenAPI memberikan skema, bukan jaminan bahwa setiap pengguna menghormatiinya. Diskusi seputar memahami __CAPGO_KEEP_0__ yang terhubung API yang Dibuat bermanfaat di sini karena memindahkan percakapan dari alat tunggal menuju bagaimana sistem terhubung.

Dimana kegagalan disembunyikan.

Titik putus yang paling umum adalah membosankan, bukan eksotis. Drift skema. terjadi ketika spesifikasi OpenAPI dan layanan yang dijalankan tidak lagi sejalan. Penggunaan sebagian. muncul ketika spesifikasi hanya menggambarkan jalur bahagia, sementara aplikasi bergantung pada kasus tepi yang tidak terdokumentasi. Penggunaan wrapper tangan. sering kali di mana jenis-jenisnya lemah, terutama ketika seseorang ingin “bergerak cepat” dan menggunakan any atau cast respons yang longgar.

Aturan praktis: jika wrapper dapat berbohong, generator tidak dapat menyelamatkan Anda.

Juga ada kesenjangan runtime. Tipe TypeScript hilang setelah kompilasi, sehingga mereka tidak dapat menolak JSON yang rusak yang datang melalui kabel. Jaringan tidak peduli apa yang diinfer oleh editor Anda, dan itu adalah mengapa klien yang dihasilkan hanya satu lapisan dalam pipa yang lebih aman API.

Pertanyaan operasional yang lebih luas adalah keamanan dan disiplin kontrak, bukan hanya kemudahan pengembang. Jika Anda ingin tampilan struktur tentang bagaimana API kontrak masuk ke dalam siklus aplikasi yang lebih besar, panduan internal ini tentang API standar keamanan untuk kinerja aplikasi di toko aplikasi adalah teman yang berguna.

Cara yang lebih dewasa untuk berpikir tentang openapi typescript adalah ini. Ini memberikan jembatan schema-to-types yang ketat, yang sangat baik, tetapi tidak memvalidasi permintaan, memaksa bentuk payload runtime, atau menghentikan wrapper yang tidak sopan dari merusak segalanya. Penghasil adalah 20 persen yang mudah. Bagian lain adalah desain pipa, dan itu adalah di mana tim mendapatkan kepercayaan atau mengumpulkan kepercayaan palsu.

Menghasilkan Tipe TypeScript dari Spesifikasi OpenAPI

Konfigurasi yang paling ringan dan berguna biasanya adalah yang dapat bertahan melalui perubahan repo yang nyata. Simpan spesifikasi OpenAPI di repositori yang sama, hasilkan file tipe yang dikomit, dan buat perubahan yang hilang terlihat di CI daripada mengandalkan seseorang untuk mengingat langkah refresh. Perintah seperti npx openapi-typescript ./openapi.yaml -o ./src/types/api.d.ts memberikan Anda file output yang deterministik yang dapat diperiksa oleh reviewer seperti perubahan sumber lainnya.

Flag yang sebenarnya berpengaruh

Flag output sangat penting karena membuat artefak yang dihasilkan eksplisit. -o berguna ketika Anda ingin jenis yang dihasilkan mempertahankan tujuan readonly di output, dan --immutable menghasilkan perbedaan stabil ketika urutan skema berubah tanpa makna semantik. --alphabetize penting ketika tim Anda lebih suka enum di permukaan yang dihasilkan daripada union. --enum Proyek dokumentasinya sendiri jelas tentang ruang lingkup, itu adalah

penghasil jenis bukan runtime klien atau lapisan permintaan, dan batasan tersebut membantu ketika Anda ingin setup yang ringan, tipe pertama.Repositorinya juga menunjukkan model perawatan di balik alat, yang merupakan bagian dari mengapa perangkat lunak terbuka dapat bertahan di produksi ketika dokumen dan rilis tetap aktif, seperti yang dibahas dalam kasus untuk perawatan terbuka. Bacaan praktis tentang postur tersebut adalah repositori proyek GitHub repository and CLI documentation.

Generasi kabel ke package.json Jadi perintah ini berada di samping skrip build lainnya, lalu jalankan ketika spesifikasi berubah. Di CI, regenerasi file dan gagal jika git diff Menggambarkan perubahan kontrak menjadi pekerjaan tinjauan yang terlihat bukan risiko runtime yang diam.

Di sisi schema, hal itu sangat penting seperti perintah baris perintah. Projek merekomendasikan compilerOptions.noUncheckedIndexedAccess agar additionalProperties menjadi T | undefinedyang memaksa indexing yang lebih aman di situs panggilan. Projek juga merekomendasikan menggunakan oneOf sendiri tanpa mencampurnya dengan komposisi tambahan, dan menjaga $defs di root ketika penempatan ambigu, karena definisi yang salah dapat hilang dari output yang dihasilkan. Detail tambahan ini dapat menghemat waktu di kemudian hari. openapi-typescript akan tidak menghasilkan anyyang hilang, sehingga detail schema yang hilang dapat muncul lebih awal bukan disembunyikan di bawah jenis yang permissive.

Jaga spesifikasi menjadi eksplisit, atau generator akan menampilkan ketidakpastian kembali ke Anda.

Alur kerja yang bertahan adalah sederhana. Masukkan spesifikasi di bawah pengawasan versi, regenerasi pada build, komit file yang dihasilkan, dan biarkan checker tipe mengeluh sebelum siapa pun menggabungkan kesalahan. Ini memberikan batasan kontrak yang stabil untuk pipa lainnya.

Pilih Antara Tipe Murni, Klien Penuh, dan Tidak Menggunakan Pengkodean

Pilihan bukanlah “alat mana yang menang”. Itu adalah bentuk pipa yang mana yang sesuai dengan repositori Anda, tim Anda, dan berapa banyak perubahan yang dilihat oleh API . Dalam benchmark 2025 di sekitar spesifikasi OpenAPI besar sekitar 75.000 baris, 2 MB, dan sekitar 1.200 operasi, openapi-typescript output yang dihasilkan dalam waktu sekitar 1,5 detik rata-rata, dibandingkan dengan sekitar 8,0 detik untuk @hey-api/openapi-ts, 5,5 detik untuk Orval, dan 18,1 detik untuk Kubb, sambil juga menghasilkan satu file keluaran tunggal versus 16 untuk hey-api, 2,719 untuk Orvaldan 3,877 untuk Kubb (detil benchmark).

Jenis data murni mengutamakan kontrol

Konfigurasi jenis data murni cocok dengan layer permintaan yang ditulis tangan karena Anda dapat menjaga runtime kecil dan permukaan API membosankan. Hal ini berpengaruh pada front end yang sensitif bundler dan aplikasi di mana satu tim mengelola spesifikasi dan konsumen. Jika Anda perlu diingatkan bahwa pengalaman pengembang bukan hanya gula sintaks, sudut pandang pengalaman pengembang lebih mudah dinilai ketika klien API Anda singkat, jelas, dan dapat disemak. pengalaman pengembang sudut pandang lebih mudah dinilai ketika klien code Anda singkat, jelas, dan dapat disemak.

Klien penuh mengutamakan kecepatan handoff

openapi-generator, hey-api, Orvaldan Kubb semua mencoba melakukan lebih dari jenis data. Hal ini dapat membantu ketika Anda ingin metode permintaan, model, dan pipa yang dihasilkan bersamaan, terutama dalam handoff besar antara tim backend dan frontend. Biaya yang jelas terlihat dalam benchmark di atas, yaitu file yang dihasilkan lebih banyak, permukaan runtime yang lebih besar, dan lebih banyak ruang untuk gesekan build ketika spesifikasi tumbuh.

tidak ada penggunaan kode favorit refaktor lokal

Konstruktor permintaan yang ditipekan dan fetch wrapper bekerja dengan baik ketika satu basis kode menguasai kedua ujung bentuk dan perubahan API sangat koordinasi. Namun, kelemahan adalah disiplin perawatan. Semakin banyak tim dan repositori yang berada di antara produsen dan konsumen, semakin besar kemungkinan layer permintaan yang ditulis tangan mengalami perubahan kecuali Anda menegakkan tes kontrak secara agresif.

Titik keputusan inti bukanlah ideologi. Jika anggaran bundle Anda sangat terbatas, tipe murni sangat menarik. Jika tim Anda ingin maksimal scaffolding dan dapat menyerap output, klien penuh dapat mengurangi waktu pengaturan. Jika Anda ingin bagian yang paling sedikit bergerak dan dapat menjaga kontrak dekat, pembuat permintaan tanpa kode dapat menjadi pilihan perdagangan internal yang tepat.

Pemasangan Klien Tipis yang Dibungkus dengan Tipis Menggunakan Fetch atau Axios

Lapisan tipis adalah di mana generator berhenti dan aplikasi code Anda dimulai. Pembungkus harus menampilkan satu fungsi per operasi, menerima parameter dan objek kueri yang ditipekan, dan mengalihkan panggilan ke fetch atau instance yang diinjeksikan axios tanpa mencoba menjadi pintar. Pada sebagian besar pengaturan produksi, lapisan ini tetap ada 30–60 baris karena jenis yang dihasilkan sudah membawa bentuk yang besar.

Berikut adalah model mental yang tetap berlaku:

• Parameter jalur tetap ditipekan sehingga /users/{id} tidak bisa disebut tanpa __CAPGO_KEEP_0__ id.
• Objek Query tetap berjenis jadi filter opsional tidak berubah menjadi sup sederhana.
• Badan respons tetap berjenis jadi pemrosesan code dapat dipercaya bentuk sempit yang diharapkan.

Sebuah wrapper seperti itu sengaja membosankan. Tidak harus menginventaris ulang retries, transformasi, atau kebijakan autentikasi jika hal itu milik tempat lain. Tugas wrapper adalah menggerakkan permintaan dari operasi yang berjenis ke lapisan transportasi dan kemudian mengembalikan hasil yang berjenis ke atas.

Tahanlah wrapper agar membosankan dan ringan ketergantungan, atau setiap perubahan kodegen di masa depan akan berdampak pada aplikasi Anda.

Gagal umumnya adalah memperbaiki kesalahan dengan as any ketika jenis yang dihasilkan tidak sesuai dengan tanda tangan wrapper lama. Ini membeli bangunan hijau dan aplikasi yang rapuh. Ini juga menyembunyikan kontrak perubahan yang Anda inginkan generator untuk mengekspos.

Untuk tim yang lebih suka Axios, pola yang sama, hanya implementasi transportasi yang berubah. Untuk tim yang ingin code sederhana di sisi browser, fetch cukup sering digunakan. Bagian penting adalah fungsi permintaan menerima jenis jalur yang dihasilkan dan mengembalikan respons yang berjenis, bukan objek yang berbentuk longgar yang kemudian diproses lebih lanjut.

Jika Anda menggunakan celah ini dengan baik, openapi typescript memberi Anda pembagian kerja yang bersih. Schema hidup di spesifikasi, transportasi hidup di pembungkus, dan aplikasi melihat operasi yang ditipekan daripada permintaan ad hoc code.

Menambahkan Validasi Runtime dengan zod, ajv, atau io-ts

Tipenya TypeScript menghilang pada runtime, dan jaringan tidak peduli dengan kepercayaan editor Anda. Itulah mengapa pola aman bukanlah 'generate tipenya dan berharap', melainkan 'generate tipenya, lalu validasi di tepi tempat data tidak terpercaya memasuki aplikasi'. Schema yang dihasilkan tetap menjadi sumber kebenaran, dan library validasi seperti zod, ajv, dan io-ts menangani periksa batas yang dapat dikompilasi oleh tipenya waktu compile.

Validasi di tempat data memasuki

Untuk aplikasi React, tepi biasanya tepat setelah permintaan diselesaikan dan sebelum payload memasuki state. Untuk server, itu sebelum payload ditulis ke dalam database atau diberikan ke aturan bisnis. Aturan sederhana, jaga validasi dekat dengan batas dan jangan menyebarkan periksa manual melalui fitur code.

A zod Bentuk dapat meniru bentuk respons yang dihasilkan tanpa menggantinya:

import { z } from "zod";

const WeatherForecastSchema = z.object({
  date: z.string(),
  temperatureC: z.number(),
  summary: z.string().nullable(),
  temperatureF: z.number().optional(),
});

Bentuk tersebut memvalidasi bidang yang schema tandai sebagai opsional, dan itu menjaga periksa waktu runtime sejalan dengan apa yang diproduksi generator. ajv adalah pilihan kuat ketika Anda ingin validasi JSON Schema dengan tingkat arus tinggi pada server, sementara io-ts masih sesuai dengan tim yang sudah hidup dalam gaya komposisi. fp-ts gaya komposisi.

kesalahan besar adalah memvalidasi terlambat. Jika payload melintasi ke aplikasi Anda terlebih dahulu, sistem tipe sudah dihindari dan bug memiliki tempat untuk bersembunyi. Panduan singkat tentang unit tests untuk JavaScript berkombinasi dengan mindset ini, karena baik unit tests dan validasi batas berfungsi paling baik ketika menangkap asumsi yang salah pada awalnya.

layering yang bersih adalah prediktif. OpenAPI TypeScript menghasilkan kontrak, validator memeriksa payload waktu eksekusi, dan aplikasi Anda code hanya melihat data yang bertahan dari kedua langkah tersebut. Itu adalah batasan yang lebih baik daripada mengandalkan tipe statis untuk memantau respons yang tidak dipercaya.

Menempatkan Pembuatan, Validasi, dan Uji Kontrak di CI

Pipeline yang berlangsung mengubah kontrak menjadi pintu, bukan saran. Regenerasi tipe, gagal pada drift, jalankan tsc --noEmit, dan uji bentuk API terhadap mock atau alat kontrak sebelum merge. Jika Anda memasang versi generator di package.jsondua insinyur tidak dapat secara tidak sengaja menghasilkan output yang berbeda dari spesifikasi yang sama.

Aksi bentuk sederhana GitHub

A alur kerja yang praktis seperti ini:

1. Pilih spesifikasi dari repositori atau sumber yang dihasilkan.
2. Regenerasi jenis.
3. Gagalkan pekerjaan jika git diff menunjukkan perubahan.
4. Jalankan tsc --noEmit.
5. Eksekusi tes kontrak terhadap mock server seperti Prism atau cek yang didukung Spectral.

Perbedaan utama antara tes kontrak dan tes snapshot adalah ruang lingkup. Tes snapshot seringkali memberitahu Anda bahwa file yang berubah. Tes kontrak memberitahu Anda apakah bentuk masih berperilaku seperti spesifikasi yang mengatakan bahwa harusnya.

A mock server is especially useful when backend and frontend work are separated by time or team boundaries. It gives consumer code a predictable API surface while still checking the actual contract rather than a hard-coded fixture. The petunjuk pengaturan integrasi terus-menerus jika tim Anda masih membutuhkan basis CI yang bersih dan dapat diulang.

Pinning versi generator menghindari salah satu kegagalan paling menyakitkan dalam pipeline codegen, yaitu ketidakstabilan output yang tidak terlihat. Jika seorang developer mengupgrade generator secara lokal dan yang lain tidak, file yang dihasilkan dapat menjadi sumber kebisingan acak bukan signal. CI harus membuat hal itu tidak mungkin.

Hasilnya adalah pipeline di mana perubahan schema, penghasilan jenis, pengecekan kompiler, dan tes kontrak semua saling memperkuat. Itulah yang membuat alur kerja menjadi jujur.

Pengaturan Pipa yang Dapat Dibangun Kembali, Kinerja, dan Checklist Akhir

Pipa yang bertahan adalah yang memiliki pengaturan pemerintahan yang membosankan. Versi spesifikasi, tinjau perubahan schema seperti code, pin generator, dan dokumentasikan bagaimana perubahan yang mengganggu mendapatkan persetujuan. Jika prosesnya kabur, orang akan mengelilinginya, dan kemudian jenis yang dihasilkan menjadi dekorasi bukan penegak.

Beberapa pengaturan kinerja yang sebenarnya berpengaruh

Penghasilan incremental membantu di monorepos di mana spesifikasi berubah sering tetapi hanya satu paket yang menggunakannya. tsc --incremental menghilangkan pekerjaan kompiler yang diulang, dan mengaktifkan flag output yang tidak dibutuhkan dalam pembangunan produksi membuat permukaan yang dihasilkan lebih kecil. Dalam prakteknya, kemenangan terbesar masih sosial, bukan teknis, karena pipa yang dapat diprediksi dijalankan lebih sering daripada yang pintar.

Daftar checklist di bawah ini adalah yang perlu Anda simpan dekat:

• Penguncian versi: Kunci openapi-typescript versi di package.json jadi hasilnya tidak akan berbeda di setiap mesin.
• Ulasan Schema: Tangani perubahan spesifikasi sebagai perubahan kontrak yang dapat diulas, bukan perawatan.
• Pengenalan Drift: Regenerasi di CI dan gagal jika ada perbedaan.
• Pengujian Pemutus: Analisis sisi pinggir sebelum payload tidak terpercaya mencapai keadaan aplikasi atau penyimpanan.
• Pengujian Kontrak: Jalankan cek yang dibalikkan oleh mock yang membuktikan bahwa konsumen code masih sesuai dengan schema.
• Kebijakan Perubahan yang Menghancuskan: Tuliskan siapa yang menyetujui perubahan bentuk dan bagaimana klien diinformasikan.

A pipa yang mencakup pintu gerbang tersebut tidak hanya menghasilkan jenis, tetapi juga membuat kontrak terlihat. Keterlihatan ini adalah apa yang mencegah tim dari percaya pada file yang hanya terlihat aman.

Jika Anda sedang mengirimkan Capacitor atau aplikasi Electron dan Anda ingin pipa update Anda berperilaku dengan disiplin yang sama, Capgo memberikan cara yang praktis untuk memindahkan perbaikan JavaScript, CSS, salinan, konfigurasi, dan aset tanpa harus menunggu tinjauan toko aplikasi. Kunjungi Capgo untuk melihat bagaimana bundel yang ditandatangani, perlindungan rollback, dan kontrol rilis masuk ke dalam proses rilis yang membutuhkan kecepatan tanpa kehilangan kendali.