Sebuah file Swagger yang rusak jarang sekali mengumumkan dirinya. YAML-nya berhasil diurai. Halaman dokumennya berhasil dirender. Kemudian seorang pengembang frontend menghasilkan klien dari spesifikasi Anda, pembangunan gagal karena bidang `required` yang hilang, dan Anda menemukan bahwa deskripsi API Anda yang "sudah selesai" memiliki kesalahan ketik dalam `$ref` tiga commit yang lalu. Spesifikasinya salah selama ini. Tidak ada yang memberi tahu Anda sampai hal itu memakan waktu sore hari seseorang.
Itulah pekerjaan yang dilakukan validator Swagger: ia membaca file OpenAPI atau Swagger Anda dan memberi tahu Anda, sebelum ada yang menggunakannya, apakah dokumen tersebut benar-benar valid. Bukan "apakah terlihat benar," tetapi "apakah sesuai dengan Spesifikasi OpenAPI, menyelesaikan setiap referensi, dan menjelaskan skema yang dapat dipercaya oleh alat." Validator mengubah bug struktural yang senyap menjadi kesalahan yang keras dan bernomor baris yang Anda perbaiki dalam hitungan detik alih-alih menghabiskan waktu berjam-jam untuk melakukan debug di kemudian hari.
Apa yang sebenarnya diperiksa oleh validator Swagger
Pertama, penamaan. "Swagger" dan "OpenAPI" menggambarkan hal yang sama pada titik sejarah yang berbeda. Format ini disebut Swagger hingga versi 2.0, kemudian disumbangkan ke OpenAPI Initiative dan dinamai ulang; 3.0, 3.1, dan 3.2 semuanya adalah OpenAPI. Orang masih mengatakan "validator swagger" karena kebiasaan, dan sebagian besar alat menerima Swagger 2.0 dan OpenAPI 3.x. Jika riwayat versi tidak jelas, penjelasan Swagger vs OpenAPI akan memperjelasnya. Untuk perbedaan antara versi terbaru, lihat perubahan pada OpenAPI 3.2 vs 3.1 vs 3.0.
Validator sungguhan melakukan tiga pekerjaan, secara berurutan:
- Penguraian (Parse). Apakah file tersebut adalah YAML atau JSON yang valid? Sebuah spasi tab yang salah, kunci duplikat, kurung yang tidak tertutup, dokumen tersebut tidak akan pernah dimuat. Ini adalah kesalahan termurah untuk ditangkap dan yang paling memalukan untuk dikirim.
- Memvalidasi struktur. Apakah dokumen tersebut sesuai dengan skema OpenAPI? Setiap operasi membutuhkan objek `responses`. Setiap parameter membutuhkan nilai `in`. Sebuah `$ref` harus menunjuk ke sesuatu yang ada. Di sinilah sebagian besar bug nyata bersembunyi.
- Menyelesaikan referensi. Dokumen OpenAPI penuh dengan penunjuk `$ref` yang menyatukan skema yang dapat digunakan kembali. Validator mengikuti setiap penunjuk dan akan gagal jika target tidak ada, melingkar dengan cara yang dilarang oleh spesifikasi, atau menunjuk ke file yang salah.
Lulus ketiga tahapan ini dan Anda memiliki dokumen yang dapat dibaca oleh alat yang sesuai, generator kode, server tiruan, perender dokumen, tanpa hambatan. Gagal pada salah satunya dan kegagalan akan muncul di tempat yang kurang nyaman daripada terminal Anda.
Kesalahan yang ditangkapnya yang bisa merugikan nanti
Validasi terasa abstrak sampai Anda melihat apa yang luput tanpa validasi. Ini adalah kesalahan spesifikasi yang terlihat tidak berbahaya di editor dan berubah menjadi insiden nyata di kemudian hari.
Penunjuk `$ref` yang rusak. Anda mengubah nama skema dari `User` menjadi `UserProfile` tetapi melewatkan satu referensi yang dalam di dalam badan respons. YAML-nya masih dapat diurai. Dokumennya masih merender sisa halaman. Generator kode mengenai penunjuk yang menggantung dan menghasilkan klien dengan tipe yang hilang, atau hanya macet. Validator akan menandai `$ref` yang rusak segera setelah Anda menyimpannya.
Ketidaksesuaian skema dan contoh. Skema Anda mengatakan `age` adalah bilangan bulat; contoh Anda menunjukkan `"age": "thirty"`. Swagger UI dengan senang hati menampilkan keduanya. Sebuah server tiruan yang dibangun dari spesifikasi kemudian mengembalikan string di mana konsumen mengharapkan angka, dan uji kontrak tiga tim jauhnya menjadi merah karena alasan yang tidak dapat dilacak kembali ke file Anda.
Bagian wajib yang hilang. Sebuah operasi tanpa `responses`. Parameter jalur yang dideklarasikan dalam template URL tetapi tidak pernah didefinisikan dalam `parameters`. Sebuah `requestBody` tanpa `content`. Masing-masing secara teknis adalah dokumen yang salah format, dan masing-masing menghasilkan gejala hilir yang berbeda tergantung pada alat mana yang membaca spesifikasi terlebih dahulu.
Penyimpangan tipe dan format. `format: date-time` pada bidang yang dikembalikan oleh backend Anda sebagai stempel waktu Unix. `type: string` pada sesuatu yang sebenarnya adalah array. Ini lulus validasi struktural tetapi merusak kontrak antara spesifikasi dan API yang berjalan, yang merupakan masalah terpisah yang akan kita bahas.
Polanya konsisten: kesalahan spesifikasi tidak terlihat pada saat Anda membuatnya dan mahal pada saat orang lain menggunakannya. Validasi menggeser biaya kembali ke tempat yang murah.
Cara memvalidasi file Swagger secara manual
Anda tidak memerlukan platform untuk memulai. Ada tiga cara cepat untuk memvalidasi spesifikasi hari ini.
Swagger Editor. Tempelkan YAML Anda ke Swagger Editor dan itu akan memvalidasi saat Anda mengetik, menggarisbawahi kesalahan dengan nomor baris di margin kanan. Ini adalah cara tercepat untuk memeriksa kewarasan satu file, dan gratis. Batasannya adalah itu adalah kotak teks tunggal: ia memvalidasi dokumen tetapi tidak melakukan apa pun tentang apakah API Anda yang sebenarnya masih cocok dengannya, dan Anda menulis YAML secara manual tanpa pembuat skema visual. Untuk mempelajari format itu tidak masalah. Untuk spesifikasi yang diandalkan tim, itu adalah satu tab dalam alur kerja yang membutuhkan beberapa tab.
Linter seperti Spectral. Spectral dari Stoplight adalah CLI sumber terbuka yang melampaui validitas mentah hingga aturan gaya. Ini memeriksa validitas struktural dan memungkinkan Anda menegakkan seperangkat aturan: setiap operasi membutuhkan deskripsi, setiap properti skema membutuhkan tipe, penamaan mengikuti konvensi Anda. Spectral benar-benar alat terbaik di kelasnya untuk mengatur gaya spesifikasi di banyak file, dan jika desain API yang konsisten adalah perhatian Anda, Spectral layak diadopsi. Anda menjalankannya seperti ini:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Komprominya adalah lingkup. Spectral memvalidasi dan melint dokumen. Ini bukan pelari permintaan; itu tidak akan memberi tahu Anda apakah API yang dijelaskan oleh spesifikasi benar-benar berperilaku seperti yang diklaim oleh spesifikasi. Itu adalah lapisan yang berbeda, dan itu adalah lapisan di mana sebagian besar kejutan produksi berada.
Titik akhir validator online. Proyek Swagger menerbitkan layanan validator yang mengembalikan lencana lulus atau gagal untuk URL spesifikasi yang di-hosting. Ini berguna untuk lencana README, tetapi kurang berguna untuk perulangan perbaikan interaktif. Untuk cakupan opsi mandiri yang lebih mendalam, kami menyajikan ringkasan alat validator OpenAPI terbaik dan panduan terfokus tentang cara memvalidasi spesifikasi OpenAPI.
Ketiganya memvalidasi dokumen. Tidak ada yang menutup celah antara spesifikasi yang valid dan API yang benar. Celah itu adalah tempat bagian selanjutnya berada.
Di mana Apidog berperan: memvalidasi spesifikasi, lalu membuktikan bahwa API cocok dengannya
Apidog adalah platform API all-in-one: Anda merancang skema, men-debug permintaan, membangun skenario pengujian otomatis, endpoint tiruan, dan memublikasikan dokumen dalam satu ruang kerja. Validasi spesifikasi bukanlah alat terpisah yang Anda pasang; itu adalah properti dari bekerja dalam platform.
Ketika Anda mengimpor file Swagger atau OpenAPI, atau mendesainnya di editor visual, Apidog mengurai dan memvalidasinya saat masuk. Dokumen yang salah format, `$ref` yang rusak, parameter tanpa tipe, ini muncul saat Anda bekerja, bukan tiga alat di hilir. Karena editornya visual, seluruh kategori kesalahan YAML yang ditulis tangan tidak pernah terjadi: Anda tidak bisa melupakan nilai `in` pada parameter ketika bidang tersebut adalah pilihan wajib. Spesifikasi ini valid berdasarkan konstruksi.
Itu menangani dokumennya. Masalah yang lebih sulit adalah penyimpangan, ketidaksepakatan lambat antara spesifikasi yang mengatakan satu hal dan API yang melakukan hal lain. Validator mandiri tidak dapat menangkap ini, karena file tersebut valid; layanan yang berjalanlah yang salah. Ini adalah mode kegagalan di balik begitu banyak dokumen Swagger dan koleksi Postman yang menyimpang.
Apidog menutupnya dengan menjadikan spesifikasi sebagai sumber kebenaran untuk pengujian. Anda menghasilkan skenario pengujian langsung dari spesifikasi OpenAPI Anda, lalu menegaskan bahwa respons nyata cocok dengan skema yang Anda deklarasikan. Ketika spesifikasi mengatakan `age` adalah bilangan bulat dan API mengembalikan string, pengujian gagal, dan gagal terhadap spesifikasi, bukan terhadap salinan yang dikelola secara manual. Pertanyaan validator menjadi pertanyaan yang berkelanjutan: bukan "apakah file ini valid saat saya menyimpannya" tetapi "apakah API langsung masih sesuai dengan kontraknya saat ini." Jika Anda ingin mekanisme penegasan, penegasan API: panduan praktis mencakup validasi bentuk respons, status, dan bidang.
Untuk tim yang ingin validasi diterapkan secara otomatis daripada diingat, Apidog juga mencakup memastikan API sesuai dengan standar OpenAPI sebagai bagian dari siklus desain.
Jalankan validasi berbasis spesifikasi di CI dengan Apidog CLI
Validator yang hanya berjalan saat seseorang membuka editor adalah validator yang pada akhirnya akan dilewati. Solusinya adalah menempatkan validasi dalam pipeline, di mana validasi berjalan pada setiap push tanpa campur tangan manusia. Itulah kegunaan Apidog command-line runner.
CLI adalah paket npm bernama `apidog-cli`. Ini menjalankan skenario pengujian yang Anda buat di Apidog, secara otomatis, dari lingkungan mana pun yang memiliki Node.js. Instal dengan satu perintah:
npm install -g @apidog/cli
Kemudian jalankan skenario tersimpan, skenario yang sama yang menegaskan respons langsung Anda cocok dengan spesifikasi, terhadap suatu lingkungan:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Beberapa catatan tentang apa yang dilakukan flag tersebut. `-t` adalah ID skenario pengujian. `-e` adalah ID lingkungan, sehingga Anda dapat mengarahkan pemeriksaan yang sama ke staging dalam permintaan tarik dan ke produksi setelah penyebaran. `-r` memilih format laporan: `cli` untuk keluaran log pembangunan yang mudah dibaca, dan Anda dapat menambahkan `html`, `json`, atau `junit` untuk mengisi dasbor CI. `--access-token` termasuk dalam rahasia CI, tidak pernah sebaris. Anda menghasilkan token dan perintah siap pakai dari tab CI/CD skenario di dalam Apidog. Untuk permukaan flag lengkap, jalankan `apidog run --help` atau baca panduan lengkap Apidog CLI.
Detail yang menjadikan ini sebuah gerbang sungguhan: CLI keluar dengan kode status bukan nol ketika sebuah penegasan gagal. Sistem CI membaca kode status keluar tersebut. Pemeriksaan skema yang gagal akan menggagalkan langkah tersebut, yang menggagalkan pekerjaan, yang memblokir penggabungan. Jadi, saat API Anda berhenti cocok dengan kontrak OpenAPI-nya, pembangunan menjadi merah, sebelum perubahan dikirim, bukan setelah konsumen mengajukan tiket. Itulah perbedaan antara memvalidasi file sekali dan memvalidasi kontrak pada setiap commit. Perilaku kode keluar yang sama adalah mengapa runner dapat masuk ke platform CI mana pun, sama seperti menjalankan koleksi Postman di CI tanpa Newman.
Unduh Apidog jika Anda ingin validasi spesifikasi dan pengujian kontrak di tempat yang sama dengan tim Anda mendesain API.
Alur kerja validasi praktis
Menggabungkan bagian-bagiannya, berikut adalah urutan yang menangkap kesalahan spesifikasi di setiap tahap daripada hanya yang terakhir:
- Desain atau impor dalam editor validasi. Baik Anda mengimpor file Swagger yang sudah ada atau membangunnya di desainer visual Apidog, dokumen akan diurai dan divalidasi secara struktural saat masuk. Referensi yang rusak dan tipe yang hilang akan segera muncul.
- Lint untuk gaya jika Anda memiliki seperangkat aturan. Jika organisasi Anda memberlakukan aturan penamaan dan deskripsi, jalankan Spectral sebagai pemeriksaan pra-commit yang cepat. Validitas dan gaya internal adalah perhatian yang berbeda; tangani keduanya.
- Hasilkan pengujian dari spesifikasi. Ubah dokumen OpenAPI menjadi skenario pengujian sehingga penegasan Anda terikat pada definisi yang sama yang Anda kirimkan, bukan salinan terpisah yang menyimpang.
- Batasi setiap push dengan CLI. Integrasikan `apidog run` ke dalam pipeline Anda sehingga ketidakcocokan spesifikasi-versus-kenyataan secara otomatis menggagalkan pembangunan.
- Perlakukan spesifikasi sebagai sumber kebenaran. Ketika desain berubah, pengujian menunjuk ke file yang sama, jadi tidak ada yang perlu disinkronkan secara manual.
Langkah 1 dan 2 memvalidasi dokumen. Langkah 3 hingga 5 memvalidasi kontrak. Anda membutuhkan keduanya, dan tempat termurah untuk melakukan semuanya adalah satu ruang kerja daripada empat tab browser.
Versi singkat
Validator Swagger menangkap bug struktural, referensi rusak, tipe hilang, YAML salah format, yang tidak terlihat saat Anda menuliskannya dan mahal saat orang lain membacanya. Memvalidasi dokumen adalah dasar, bukan puncak. Kesalahan yang benar-benar mencapai produksi adalah yang spesifikasi validnya secara diam-diam berhenti cocok dengan API yang berubah, dan tidak ada validator tingkat file yang dapat melihatnya.
Solusinya adalah memvalidasi dalam dua lapisan dan menempatkan keduanya di satu tempat: memvalidasi dokumen saat Anda mendesainnya, lalu memvalidasi kontrak pada setiap push dengan menegaskan respons nyata terhadap spesifikasi. Apidog melakukan yang pertama secara bawaan dan yang kedua melalui skenario yang dibatasi oleh `apidog-cli` di CI. Spesifikasi tetap menjadi sumber kebenaran, pembangunan menjadi merah saat realitas menyimpang darinya, dan file Swagger yang rusak berhenti menjadi sesuatu yang Anda temukan satu sore terlalu terlambat.