OpenAPI TypeScript: Buat Tipe, Klien, dan Validasi

Anda biasanya dapat mengenali 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 utuh.

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 Tanpa Pengkodean
  • Tipe Murni Memprioritaskan Kontrol
  • Klien Penuh Memprioritaskan Kecepatan Pengiriman
  • Tanpa Pengkodean Memprioritaskan Refaktor Lokal
• Menghubungkan Klien Tipe Tipis Sekitar Fetch atau Axios
• Menambahkan Validasi Waktu Eksekusi dengan zod, ajv, atau io-ts
  • Memeriksa di mana data masuk
• Menggunakan Pengujian Penerbitan, Pengujian Validasi, dan Pengujian Kontrak di CI
  • Gaya Aksi Sederhana GitHub
• Alur Pipa yang Dapat Diperbarui, Kinerja, dan Checklist Akhir
  • Beberapa Pengaturan Kinerja yang Sebenarnya Berpengaruh

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

Saat 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 cast dengan as any, dan produksi mulai berperilaku seperti kontrak tidak pernah berubah.

Perangkap itu dengan tipe-tipe yang dibuat. TypeScript hanya dapat melindungi code yang mengonsumsi tipe-tipe yang dibuat, dan hanya jika lapisan transportasi tidak menghapus kontrak lagi. Sisi OpenAPI memberikan skema, bukan jaminan bahwa setiap pengguna menghormatiinya. Diskusi mengenai memahami API yang terhubung bermanfaat di sini karena menggeser percakapan dari alat tunggal menuju bagaimana sistem terhubung.

Dimana kegagalan disembunyikan

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

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

Ada juga celah waktu eksekusi. Tipe TypeScript hilang setelah kompilasi, sehingga mereka tidak dapat menolak JSON yang rusak yang datang melalui kabel. Jaringan tidak peduli apa yang disarankan editor Anda, dan itu 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 bagaimana API kontrak masuk ke dalam siklus hidup 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 muatan waktu eksekusi, atau menghentikan wrapper yang tidak teliti dari merusak segalanya. Penghasil adalah 20 persen yang mudah. Bagian lain adalah desain pipa, dan itu di mana tim-tim mendapatkan kepercayaan atau mengumpulkan kepercayaan palsu.

Menghasilkan Tipe TypeScript dari Spec OpenAPI

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

Flag yang sebenarnya berpengaruh

Mengapa Flag Keluaran Penting -o flag keluaran sangat penting karena membuat artefak yang dihasilkan menjadi eksplisit. --immutable berguna ketika Anda ingin jenis yang dihasilkan mempertahankan niat readonly di keluaran, dan --alphabetize menjaga perbedaan stabil ketika urutan skema berubah tanpa makna semantik. --enum penting ketika tim Anda lebih suka enum di permukaan yang dihasilkan daripada union.

Dokumentasi proyek sendiri jelas tentang ruang lingkup, itu adalah penghasil jenisbukan runtime klien atau lapisan permintaan, dan batasan tersebut membantu ketika Anda ingin setup ringan, jenis pertama. repositorynya 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 dalamalasan untuk perawatan terbuka GitHub repository and CLI documentation.

Wire generation into package.json Jadi perintah itu berada di samping skrip build lainnya, lalu jalankan ketika spesifikasi berubah. Di CI, regenerasi file dan gagal jika git diff Menunjukkan pergeseran. Itu mengubah perubahan kontrak menjadi pekerjaan tinjauan yang terlihat bukan risiko runtime yang diam.

Sisi schema berpengaruh sama seperti perintah baris perintah. Projek merekomendasikan compilerOptions.noUncheckedIndexedAccess menjadi additionalProperties menjadi T | undefined, yang memaksa indeks 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 satu ini dapat menghemat waktu di kemudian hari. openapi-typescript akan tidak pernah menghasilkan any, sehingga detail schema yang hilang dapat muncul lebih awal bukan disembunyikan di bawah jenis yang permissive.

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

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

Pilih Antara Pure Types, Klien Penuh, dan Tidak Ada 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 sekitar OpenAPI besar sekitar 75,000 baris, 2 MB, dan sekitar 1,200 operasi Dikeluarkan dalam waktu sekitar, openapi-typescript 75,000 baris, 2 MB, dan sekitar 1,200 operasi 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 (detail benchmark).

Jenis tipe murni mengutamakan kontrol

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

Klien penuh mengutamakan kecepatan handoff

openapi-generator, hey-api, Orval, dan Kubb semua mencoba melakukan lebih dari jenis tipe. 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 dalam benchmark di atas adalah file yang dihasilkan lebih banyak, permukaan runtime yang lebih besar, dan lebih banyak ruang untuk gesekan pembangunan seiring spesifikasi tumbuh.

Tidak ada penggunaan kode mengutamakan refaktor lokal

Konstruktor permintaan yang ditipekan dan fetch Penggunaan wrapper sangat 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.

Poin keputusan inti bukanlah ideologi. Jika anggaran bundel 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 yang tepat.

Pemasangan Klien Tipis yang Dibungkus dengan Tipis Menggunakan Fetch atau Axios

Penggunaan wrapper tipis adalah titik di mana generator berhenti dan aplikasi code Anda dimulai. Penggunaan wrapper 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, layer tersebut tetap ada 30–60 baris sebab jenis yang dihasilkan sudah membawa bentuk yang paling 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 kacang.
• Badan respons tetap berjenis jadi parsing code dapat percaya 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. Tidak harus menggerakkan permintaan dari operasi yang berjenis ke lapisan transportasi dan kemudian mengembalikan hasil yang berjenis ke atas.

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

Gagal umum adalah untuk 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 perubahan kontrak yang Anda inginkan generator untuk menunjukkan.

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

Jika Anda menggunakan celah ini dengan baik, typescript openapi memberikan 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 yang 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 berada di sebelah setelah permintaan diselesaikan dan sebelum payload memasuki state. Untuk server, itu sebelum payload ditulis ke dalam database atau diserahkan ke aturan bisnis. Aturan sederhana, jaga validasi dekat dengan batas dan jangan menyebarkan periksa manual melalui fitur code.

A zod bentuk dapat mengacu 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(),
});

Contoh tersebut memvalidasi bidang yang schema tandai sebagai opsional, dan menjaga periksa waktu runtime sejalan dengan apa yang diproduksi generator. ajv adalah pilihan yang 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 pertama, 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 terbaik ketika menangkap asumsi buruk pada awalnya.

layering yang bersih adalah prediktif. OpenAPI TypeScript menghasilkan kontrak, validator memeriksa payload waktu runtime, dan aplikasi 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

Alur yang berlangsung mengubah kontrak menjadi pintu, bukan saran. Regenerasi tipe, gagal pada perubahan, 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 adalah referensi yang berguna jika tim Anda masih membutuhkan basis CI yang bersih dan dapat diulang.

Pinning versi generator menghindari salah satu kegagalan yang paling menyakitkan dalam pipeline codegen, 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 uji kontrak semuanya memperkuat satu sama lain. Itulah yang membuat alur kerja menjadi jujur.

Pengaturan Pipa yang Dapat Dibandingkan, Kinerja, dan Daftar Periksa Terakhir

Pipa yang bertahan adalah yang memiliki pengaturan 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 mengurangi pekerjaan kompiler yang diulang, dan menghapus flag output yang tidak diperlukan dalam pembangunan produksi menjaga 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 periksa 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 persistensi.
• Pengujian Kontrak: Lakukan pengecekan palsu yang dibalik untuk membuktikan bahwa konsumen code masih sesuai dengan schema.
• Kebijakan Perubahan Pemutus: Tuliskan siapa yang menyetujui perubahan bentuk dan bagaimana klien diinformasikan.

Pipa yang mencakup pintu gerbang tersebut tidak hanya menghasilkan jenis, tetapi juga membuat kontrak terlihat. Keterlihatan ini lah yang membuat tim tidak percaya pada file yang hanya terlihat aman.

Jika Anda sedang mengirimkan aplikasi Capacitor atau Electron dan Anda ingin pipeline pembaruan 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 Tulis oleh