OpenAPI TypeScript: Generate Types, Clients, dan Validasi

Anda biasanya dapat menemukan saat API pipeline mulai berbohong kepada tim. Sebuah schema berubah, jenis-jenis yang dihasilkan diperbarui tanpa keluhan, PR berwarna hijau, dan kemudian seseorang di frontend terus membaca bentuk respons lama karena wrapper menghilangkan 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 mana bagian yang harus gagal cepat pada waktu build daripada bocor ke waktu eksekusi? Setelah Anda membentuk OpenAPI TypeScript sebagai pilihan pipa, kelebihan dan kekurangan menjadi lebih jelas, dan alat-alat berhenti berpura-pura menjadi solusi utuh.

Daftar Isi

• Mengapa Tipe yang Dibuat Tidak Sama dengan API yang Aman
  • Dimana kegagalan disembunyikan
• Menghasilkan Tipe TypeScript dari Spesifikasi OpenAPI
  • Flag yang sebenarnya berpengaruh
• Memilih Antara Tipe Murni, Klien Penuh, dan Tanpa Pengkodean
  • Tipe murni memilih kontrol
  • Klien penuh memilih kecepatan handoff
  • Tanpa pengkodean memilih refaktor lokal
• Menghubungkan Klien Tipis yang Dibungkus dengan Fetch atau Axios
• Menambahkan Validasi Waktu Eksekusi dengan zod, ajv, atau io-ts
  • Memastikan di mana data masuk
• Mengatur Pengujian Generasi, Validasi, dan Kontrak di CI
  • Bentuk Aksi Sederhana GitHub
• Pengaturan Pipa yang Terjaga, Kinerja, dan Checklist Akhir
  • Beberapa Pengaturan Kinerja yang Sebenarnya Berpengaruh

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

Seseorang 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 menghormatinya. Diskusi seputar memahami __CAPGO_KEEP_0__ yang terhubung discussion around understanding API connections bermanfaat di sini karena itu mendorong percakapan menjauh dari alat tunggal dan 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 diimplementasikan berhenti sejalan. Koverasi sebagian muncul ketika spesifikasi hanya menggambarkan jalur bahagia, sementara aplikasi bergantung pada kasus tepi yang tidak terdokumentasikan. Pengikat 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 pengikat dapat berbohong, generator tidak dapat menyelamatkan Anda.

There juga ada 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 editor Anda infer, dan itu mengapa klien yang dihasilkan hanya satu lapisan dalam pipa yang lebih aman API.

Kuesioner 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 hidup aplikasi yang lebih besar, panduan internal ini tentang API standar keamanan untuk kelayakan toko aplikasi API security standards for app store compliance Cara yang matang untuk berpikir tentang openapi typescript adalah ini. Ini memberikan jembatan schema-to-types yang ketat, yang sangat baik, tetapi tidak memvalidasi permintaan, mengenakan bentuk payload waktu eksekusi, atau menghentikan wrapper yang kurang teliti dari menghancurkan segalanya. Penghasil adalah 20 persen yang mudah. Sisanya adalah desain pipa, dan itu di mana tim-tim mendapatkan kepercayaan atau mengumpulkan kepercayaan palsu.

Menghasilkan Tipe TypeScript dari Spesifikasi OpenAPI Screenshot dari https://openapi-ts.dev Pengaturan yang paling ringan dan berguna biasanya adalah yang yang 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

memberikan Anda file output yang deterministik yang dapat diperiksa oleh reviewer seperti perubahan sumber lainnya.

__CAPGO_KEEP_0__ npx openapi-typescript ./openapi.yaml -o ./src/types/api.d.ts __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

The -o flag keluaran sangat penting karena membuat artefak yang dihasilkan eksplisit. --immutable berguna ketika Anda ingin tipe yang dihasilkan mempertahankan niat readonly di keluaran, dan --alphabetize menggunakan 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 tipe, bukan runtime klien atau lapisan permintaan, dan batasan tersebut membantu ketika Anda ingin setup yang ringan, tipe pertama. Repository proyek sendiri juga menunjukkan model perawatan di balik alat, yang merupakan bagian dari mengapa perangkat lunak sumber terbuka dapat bertahan di produksi ketika dokumen dan rilis tetap aktif, seperti yang dibahas dalamkasus untuk perawatan sumber terbuka GitHub repository and CLI documentation.

__CAPGO_KEEP_0__ dan __CAPGO_KEEP_1__ 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 perbedaan. Perubahan kontrak berubah menjadi pekerjaan tinjauan yang terlihat bukan risiko runtime yang diam.

Bagian schema berpengaruh sebanding dengan perintah baris. Projek merekomendasikan compilerOptions.noUncheckedIndexedAccess Jadi additionalProperties menjadi T | undefined, yang memaksa indexing yang lebih aman di situs panggilan. Ini juga merekomendasikan menggunakan oneOf sendiri bukan campuran dengan komposisi tambahan, dan menjaga $defs di root ketika penempatan ambigu, karena definisi yang salah dapat hilang dari output yang dihasilkan. Detail tambahan ini menyelamatkan waktu di kemudian hari, openapi-typescript tidak akan menghasilkan any, sehingga detail schema yang hilang dapat muncul lebih awal bukan disembunyikan di bawah jenis yang permissive.

Tetapkan spesifikasi secara eksplisit, atau generator akan mengekspos 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. Ini memberikan batasan kontrak yang stabil untuk pipa lainnya.

Memilih Antara Tipe Murni, Klien Penuh, dan Tidak Ada Pengkodean Kode

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 tahun 2025 sekitar OpenAPI besar sekitar 75,000 baris, 2 MB, dan sekitar 1,200 operasi, openapi-typescript output yang dihasilkan dalam waktu sekitar 1,5 detik 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 output 16 versus hey-api, 2,719 untuk Orvaldan 3,877 untuk Kubb (detail benchmark).

Tipe murni lebih mengutamakan kontrol

Konfigurasi tipe murni cocok dengan layer permintaan yang ditulis tangan karena Anda dapat menjaga ukuran 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, maka pandangan pengalaman pengembang lebih mudah dipahami ketika klien code singkat, jelas, dan dapat direview.

Pengguna klien penuh mengutamakan kecepatan handoff

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

Tidak ada penggunaan kode favorit refaktor lokal

Pembuat permintaan yang ditipekan dan fetch Pengemasan berfungsi 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 mungkin layer permintaan yang ditulis tangan mengalami perubahan kecuali Anda menegakkan tes kontrak secara agresif.

Poin keputusan inti bukanlah ideologis. 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-bagian yang minimal dan dapat menjaga kontrak dekat, pembuat permintaan tanpa kode dapat menjadi pilihan yang tepat untuk perdagangan internal.

Menghubungkan Klien Tipis yang Tipekan Menggunakan Fetch atau Axios

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

Berikut adalah model mental yang tetap berlaku:

• Parameter jalur tetap ditipekan sehingga /users/{id} tidak bisa dipanggil tanpa __CAPGO_KEEP_0__ id.
• Objek Query tetap berjenis jadi filter yang opsional tidak berubah menjadi sup kacang.
• Tubuh respons tetap berjenis jadi parsing code dapat percaya bentuk sempit yang diharapkan.

Wrapper seperti itu sengaja membosankan. Tidak harus menciptakan 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.

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

Kegagalan umum 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 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 longgar yang kemudian diproses lebih lanjut. openapi typescript memberikan Anda pembagian kerja yang bersih. Schema hidup di spesifikasi, transport hidup di pembungkus, dan aplikasi melihat operasi yang ditipekan daripada permintaan ad hoc code.

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

Jenis data TypeScript menghilang pada waktu eksekusi, dan jaringan tidak peduli dengan kepercayaan editor Anda. Itulah mengapa pola aman bukanlah “buat jenis dan harap”, tetapi “buat jenis, lalu validasi di tepi tempat data tidak terpercaya memasuki aplikasi”. Schema yang dihasilkan tetap menjadi sumber kebenaran, dan library validasi seperti zod, ajvdan io-ts menangani periksa batas yang tidak dapat dilakukan jenis data waktu kompilasi.

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 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 itu memvalidasi bidang yang schema tandai sebagai opsional, dan itu menjaga periksa waktu eksekusi sejalan dengan apa yang diproduksi generator. ajv adalah pilihan kuat ketika Anda ingin validasi JSON Schema tinggi-tinggi pada server, sementara io-ts masih sesuai dengan tim yang sudah hidup dalam gaya komposisi. fp-ts Gagal besar adalah memvalidasi terlalu lambat. 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 cocok dengan mindset ini, karena baik unit tests dan validasi batas berfungsi terbaik ketika menangkap asumsi buruk pada awalnya. Lapisan yang bersih adalah prediktif.

OpenAPI TypeScript menghasilkan kontrak, validator memeriksa payload waktu eksekusi, dan aplikasi Anda __CAPGO_KEEP_0__ hanya melihat data yang bertahan dari kedua langkah tersebut. Itu adalah batas yang lebih baik daripada mengandalkan tipe statis untuk memantau respons yang tidak dipercaya. generates the contract, the validator checks the runtime payload, and your app code only sees data that survived both steps. That’s a much better boundary than trusting a static type to police an untrusted response.

Screenshot dari https://__CAPGO_KEEP_0__.com

, dan latih bentuk __CAPGO_KEEP_0__ terhadap mock atau alat kontrak sebelum merge. Jika Anda memasang versi penerbit dalam tsc --noEmit, and exercise the API shape against a mock or contract tool before merge. If you pin the generator version in package.jsondua insinyur tidak dapat secara tidak sengaja menghasilkan output yang berbeda dari spesifikasi yang sama.

Aksi bentuk GitHub yang sederhana

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. Jalankan tes kontrak terhadap server palsu 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 yang spesifikasi katakan bahwa itu harus.

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 panduan pengaturan integrasi terus-menerus adalah referensi yang berguna jika tim Anda masih membutuhkan basis CI yang bersih, ulang, dan dapat diulang.

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

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

Pengaturan Pipa yang Dapat Dibersihkan, Kinerja, dan Checklist Akhir

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

Beberapa pengaturan kinerja yang sebenarnya berpengaruh

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

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

• Penguncian versi: Mengunci versi generator openapi-typescript versi di package.json jadi output tidak bergeser di antara mesin.
• Ulasan Schema: Tangani perubahan spesifikasi sebagai perubahan kontrak yang dapat diulas, bukan perawatan rumah.
• Pengenalan Drift: Regenerasi di CI dan gagal pada perbedaan.
• Pengujian Pinggir: Analisis payload tidak dipercaya sebelum mencapai aplikasi atau penyimpanan.
• Pengujian Kontrak: Jalankan cek yang didukung mock yang membuktikan konsumen code masih sesuai dengan schema.
• Kebijakan Perubahan Patah: Tuliskan siapa yang menyetujui perubahan bentuk dan bagaimana klien diinformasikan.

A pipa yang termasuk pintu-pintu itu tidak hanya menghasilkan jenis, tetapi juga membuat kontrak terlihat. Keterlihatan itu lah yang membuat tim tidak percaya pada file yang hanya terlihat aman.

Jika Anda sedang mengirimkan Capacitor atau aplikasi 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 dengan cepat tanpa harus menunggu tinjauan toko aplikasi. Visiti Capgo untuk melihat bagaimana bundel yang ditandatangani, perlindungan rollback, dan kontrol rilis masuk ke dalam proses rilis yang membutuhkan kecepatan tanpa kehilangan kendali. Ditulis oleh