Spesifikasi OpenAPI adalah sebuah kontrak. Generator kode membacanya, dokumentasi dibangun darinya, server mock berjalan di atasnya, dan SDK klien diproduksi darinya. Ketika spesifikasi salah, setiap artefak hilir tersebut akan mewarisi kesalahan. Sebuah validator menangkap masalah dalam file spesifikasi, sebelum menyebar.
Ringkasan ini membahas alat validator OpenAPI yang patut digunakan, apa keunggulan masing-masing, dan bagaimana mereka cocok dalam alur kerja yang sebenarnya. Beberapa memeriksa sintaksis mentah. Yang lain menegakkan aturan gaya dan desain. Pengaturan terbaik biasanya menggabungkan keduanya, dan panduan ini menjelaskan cara merakitnya.
Mengapa validasi spesifikasi itu penting
Ada dua masalah berbeda yang dipecahkan oleh validator, dan mengaburkan keduanya menyebabkan kebingungan.
Yang pertama adalah kebenaran. Apakah file tersebut valid OpenAPI sama sekali? Sebuah blok YAML yang salah indentasi, sebuah $ref yang tidak menunjuk ke mana-mana, sebuah respons yang kehilangan description yang wajib, sebuah skema dengan kesalahan ketik pada nama tipe. Ini adalah kesalahan objektif. File tersebut akan terurai berdasarkan skema OpenAPI atau tidak. Validator kebenaran memberi Anda jawaban ya atau tidak.
Yang kedua adalah kualitas. Spesifikasi valid, tetapi apakah itu baik? Setiap operasi harus memiliki ringkasan. Nama path harus konsisten. Setiap respons kesalahan harus didokumentasikan. Keamanan harus dideklarasikan. Tidak satu pun dari ini yang diwajibkan oleh skema OpenAPI, tetapi melewatkannya menghasilkan spesifikasi yang secara teknis valid namun sulit untuk digunakan. Sebuah linter menegakkan aturan desain ini. Menangkap kedua kelas masalah ini lebih awal jauh lebih murah daripada menangkapnya setelah SDK dikirimkan, yang merupakan logika yang sama di balik pengujian kontrak API secara lebih luas.
Alat validator yang patut diketahui
Swagger Editor
Swagger Editor adalah editor berbasis peramban resmi dari proyek OpenAPI. Anda menempel atau menulis spesifikasi Anda di sisi kiri dan melihat kesalahan validasi serta pratinjau yang dirender di sisi kanan, secara langsung. Ini adalah cara tercepat untuk memeriksa apakah spesifikasi valid secara sintaksis, tanpa pengaturan apa pun. Ini sangat baik untuk pengeditan dan pemeriksaan cepat, kurang cocok untuk menjalankan pipeline otomatis. Swagger Editor gratis dan berjalan sepenuhnya di peramban.
Spectral
Spectral, dari Stoplight, adalah linter yang paling sering dipilih tim untuk penegakan kualitas. Ini menyediakan set aturan untuk OpenAPI dan AsyncAPI, dan nilai sebenarnya adalah aturan kustom. Anda menulis aturan dalam YAML atau JavaScript untuk menegakkan konvensi Anda sendiri, seperti mewajibkan setiap operasi memiliki deskripsi atau melarang garis miring di akhir path. Ini berjalan dari baris perintah, yang menjadikannya sangat cocok untuk CI. Proyek Spectral bersifat open source.
openapi-spec-validator
openapi-spec-validator adalah alat Python terfokus yang melakukan satu pekerjaan dengan baik: ia memeriksa spesifikasi terhadap skema OpenAPI resmi untuk versi 2.0, 3.0, dan 3.1. Ia tidak memiliki pendapat tentang gaya. Ia memberi tahu Anda apakah file tersebut benar secara struktural. Sebagai pustaka atau CLI, ia dapat disisipkan dengan rapi ke dalam langkah-langkah *build* berbasis Python dan *pre-commit hooks*. Ketika Anda menginginkan gerbang kebenaran *pass-or-fail* yang ketat, ini adalah pilihan yang tepat.
Apidog
Apidog memvalidasi spesifikasi sebagai bagian dari alur kerja desain terintegrasi. Saat Anda membangun atau mengimpor definisi OpenAPI, ia menandai masalah struktural di editor. Fitur yang lebih khas adalah validasi runtime: ia memeriksa respons API langsung terhadap skema yang dideklarasikan dalam spesifikasi Anda, sehingga Anda menangkap penyimpangan di mana implementasi tidak lagi cocok dengan kontrak. Ini menutup celah antara dokumen yang valid dan API yang benar. Unduh Apidog untuk mendesain dan memvalidasi spesifikasi dalam satu alat.
Redocly CLI
Redocly CLI menggabungkan *linting*, validasi, dan pembuatan dokumentasi. Ini memvalidasi terhadap skema OpenAPI, menyediakan set aturan yang dapat dikonfigurasi, dan dapat menggabungkan spesifikasi multi-file menjadi satu bundel. Tim yang sudah merender dokumen dengan Redoc mendapatkan validasi dalam *toolchain* yang sama tanpa menambahkan dependensi lain.
Vacuum
Vacuum adalah *linter* OpenAPI cepat yang ditulis dalam Go. Keunggulan utamanya adalah kecepatan pada spesifikasi yang sangat besar, di mana beberapa *linter* berbasis JavaScript melambat. Ini kompatibel dengan aturan gaya Spectral, sehingga tim dapat beralih dengan sedikit pekerjaan ulang. Untuk *monorepo* dengan permukaan API yang luas, perbedaan kinerjanya sangat terlihat.
Tabel perbandingan
| Alat | Tipe | Memeriksa | Berjalan di CI | Terbaik untuk |
|---|---|---|---|---|
| Swagger Editor | Editor peramban | Sintaksis, skema | Tidak | Pengeditan langsung dan pemeriksaan cepat |
| Spectral | Linter CLI | Gaya, aturan kustom | Ya | Menegakkan konvensi desain |
| openapi-spec-validator | CLI / Pustaka Python | Kebenaran skema | Ya | Gerbang *pass-or-fail* yang ketat |
| Apidog | Platform terintegrasi | Skema + penyimpangan runtime | Ya | Desain ditambah validasi respons |
| Redocly CLI | CLI | Skema, gaya, penggabungan | Ya | Dokumen dan validasi bersamaan |
| Vacuum | Linter CLI | Gaya, aturan Spectral | Ya | Spesifikasi sangat besar, kecepatan |
Cara merakit alur kerja validasi
Anda tidak memilih satu alat. Anda melapisi mereka.
Mulai dari tempat Anda mengedit. Saat menulis spesifikasi, gunakan Swagger Editor atau platform terintegrasi agar kesalahan muncul saat Anda mengetik. Ini segera menangkap kesalahan yang jelas dan jauh lebih murah daripada menangkapnya nanti.
Tambahkan gerbang kebenaran di CI. Jalankan openapi-spec-validator atau setara CLI pada setiap *pull request* yang menyentuh spesifikasi. Jika file tidak tervalidasi terhadap skema OpenAPI, *build* akan gagal. Ini tidak bisa dinegosiasikan dan bersifat biner.
Tambahkan gerbang kualitas di sampingnya. Jalankan Spectral, atau Vacuum pada spesifikasi besar, dengan set aturan yang disetujui tim Anda. Mulailah dengan aturan OpenAPI bawaan, lalu tambahkan aturan kustom untuk konvensi Anda sendiri. Simpan set aturan dalam kontrol versi agar berkembang seiring dengan API. Ini adalah disiplin yang sama yang membuat otomatisasi pengujian di CI/CD dapat diandalkan: pemeriksaan berjalan setiap saat, bukan saat seseorang ingat.
Terakhir, validasi API yang berjalan terhadap spesifikasi. Sebuah spesifikasi bisa sempurna sementara implementasinya telah menyimpang darinya. Validasi runtime, baik melalui Apidog atau pengujian kontrak dalam *suite* Anda, mengonfirmasi bahwa API masih cocok dengan kontraknya. Untuk sisi pengujian, menulis *assertion* API yang berguna mencakup cara memeriksa respons terhadap skema yang didokumentasikan.
Kesalahan umum: memvalidasi sekali saja
Banyak tim memvalidasi spesifikasi sekali, saat pertama kali menulisnya, lalu tidak pernah lagi. Spesifikasi akan membusuk dari sana. Seorang pengembang menambahkan *endpoint* dalam kode dan melupakan spesifikasi. Seseorang mengubah bentuk respons. Enam bulan kemudian, spesifikasi tersebut menjelaskan API yang tidak lagi ada, dan SDK serta dokumen yang dihasilkan diam-diam salah.
Validasi harus berkelanjutan. Masukkan ke dalam CI sehingga setiap perubahan pada spesifikasi diperiksa, dan setiap perubahan pada API diperiksa terhadap spesifikasi. Perlakukan kegagalan spesifikasi sama seperti Anda memperlakukan pengujian unit yang gagal: *build* tidak akan lolos. Prinsipnya sama dengan yang ada di balik pengujian otomatis secara umum, yaitu bahwa pemeriksaan hanya berharga jika berjalan tanpa ada yang memutuskan untuk menjalankannya.
Juga membantu untuk memvalidasi terhadap versi OpenAPI yang benar. Rilis 3.1 menyelaraskan OpenAPI dengan JSON Schema, yang mengubah perilaku beberapa konstruksi skema. Jika *tooling* Anda mengasumsikan 3.0 tetapi spesifikasi Anda mendeklarasikan 3.1, Anda bisa mendapatkan hasil yang menyesatkan. Spesifikasi OpenAPI resmi mendokumentasikan perbedaan versi, dan sebagian besar validator memungkinkan Anda menentukan versi secara eksplisit.
Apa yang ditangkap validator yang mungkin Anda lewatkan
Penting untuk lebih spesifik tentang jenis masalah yang diungkap oleh validasi, karena "spesifikasi salah" terlalu samar untuk ditindaklanjuti.
Kesalahan struktural adalah yang paling mudah dibayangkan. Sebuah $ref yang menunjuk ke skema yang tidak ada. Objek respons tanpa description, yang diwajibkan oleh OpenAPI. Parameter *path* yang dideklarasikan dalam template URL tetapi tidak pernah didefinisikan dalam daftar parameters. Sebuah skema yang menyatakan type: integer sementara contoh menunjukkan string. Sebuah validator kebenaran akan menandai setiap masalah ini, dan masing-masing jika tidak ditangkap akan merusak generator kode atau menghasilkan SDK yang rusak.
Masalah kualitas lebih halus dan lebih umum. Sebuah operasi tanpa operationId, yang membuat nama metode klien yang dihasilkan jelek atau tidak stabil. Inkonsistensi penulisan huruf *path*, di mana beberapa rute menggunakan snake_case dan yang lain menggunakan camelCase. *Endpoint* yang mendokumentasikan respons 200 tetapi tidak pernah 400 atau 401, sehingga konsumen tidak tahu seperti apa bentuk kesalahan. Badan permintaan yang ditandai opsional padahal API sebenarnya membutuhkannya. Tidak satu pun dari ini yang merusak *parser*, tetapi semuanya membuat API lebih sulit digunakan, dan *linter* adalah alat yang menjaga batas. Hubungan dengan perilaku nyata adalah apa yang diverifikasi oleh pengujian kontrak API setelah spesifikasi itu sendiri bersih.
Menyesuaikan validasi ke dalam alur kerja *design-first*
Banyak tim sekarang mendesain API sebelum menulis kode, menghasilkan spesifikasi OpenAPI terlebih dahulu dan membuat *stub* server, *mock*, dan dokumen darinya. Validasi menjadi lebih penting dalam model itu, karena spesifikasi bukanlah dokumentasi API yang ada; itu adalah sumber kebenaran dari mana semuanya dibangun. Cacat dalam spesifikasi menjadi cacat dalam server yang dihasilkan.
Dalam alur *design-first*, lakukan validasi pada saat desain. Pemeriksaan tingkat editor menangkap kesalahan saat spesifikasi terbentuk, sebelum *code generation* berjalan. Kemudian gerbang CI mengonfirmasi tidak ada yang mengalami regresi. Karena spesifikasi juga mendorong *mock server*, spesifikasi yang bersih berarti *mock* berperilaku dengan benar, yang memungkinkan tim *front-end* dan klien membangun berdasarkan pengganti yang dapat dipercaya. Jika Anda ingin melihat bagaimana spesifikasi mendukung *mocking*, panduan kami tentang membuat *mock* API untuk pengujian menunjukkan koneksinya. Disiplin ini membuahkan hasil: setiap jam yang dihabiskan untuk menjaga spesifikasi tetap valid menghemat beberapa jam *debugging* klien yang tidak cocok di kemudian hari.
Pertanyaan yang sering diajukan
Apa perbedaan antara validator OpenAPI dan *linter*?
Validator memeriksa apakah spesifikasi benar secara struktural terhadap skema OpenAPI, memberikan jawaban lulus atau gagal. *Linter* memeriksa kualitas dan gaya, seperti apakah setiap operasi memiliki deskripsi atau apakah penamaan *path* konsisten. Banyak alat melakukan keduanya, tetapi mereka menjawab pertanyaan yang berbeda, dan alur kerja yang kuat menggunakan keduanya.
Bisakah saya memvalidasi spesifikasi OpenAPI secara gratis?
Ya. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI, dan Vacuum semuanya gratis dan *open source*. Apidog memvalidasi spesifikasi pada tingkat gratisnya dan menambahkan pemeriksaan runtime. Tidak ada alasan untuk melewatkan validasi berdasarkan biaya.
Haruskah saya memvalidasi OpenAPI 3.0 dan 3.1 secara berbeda?
Anda memvalidasinya dengan alat yang sama, tetapi tentukan versinya. OpenAPI 3.1 selaras dengan JSON Schema dan mengubah beberapa perilaku skema, jadi validator yang mengharapkan 3.0 mungkin melaporkan kesalahan palsu pada spesifikasi 3.1. Pastikan *tooling* Anda mendukung versi yang dideklarasikan spesifikasi Anda.
Di mana validasi spesifikasi harus berjalan?
Di dua tempat. Secara langsung di editor Anda saat menulis spesifikasi, agar kesalahan segera muncul, dan di CI pada setiap *pull request*, sehingga tidak ada yang digabungkan dengan spesifikasi yang rusak atau berkualitas rendah. Validasi hanya di editor mudah dilewatkan; validasi CI tidak.
Bagaimana cara memeriksa bahwa API saya cocok dengan spesifikasinya?
Validasi spesifikasi hanya mengkonfirmasi bahwa dokumen benar, bukan bahwa implementasinya cocok. Untuk menangkap penyimpangan, jalankan *contract tests* atau validasi runtime yang membandingkan respons API langsung dengan skema dalam spesifikasi. Apidog melakukan ini secara langsung, dan *framework contract testing* melakukannya dalam *test suite*.