OpenAPI Diff & Pemeriksa Breaking Change

OpenAPI Diff membandingkan spesifikasi API dasar dan kandidat berdasarkan maknanya, bukan teksnya. Alat ini mencocokkan operasi berdasarkan metode dan path (sehingga /users/{id} dan /users/{userId} dianggap endpoint yang sama), menyelesaikan referensi $ref internal, dan melaporkan setiap perubahan kontrak beserta operasi, lokasi, nilai sebelum dan sesudah, serta alasan perubahan itu penting bagi klien. Swagger 2.0, OpenAPI 3.0, dan OpenAPI 3.1 dalam format JSON atau YAML didukung, dan Swagger 2.0 dinormalisasi lebih dulu ke bentuk OpenAPI 3.

1. 1.Tempel, unggah, atau impor spesifikasi dasar (versi yang dipakai klien saat ini).
2. 2.Tambahkan spesifikasi kandidat (versi yang diusulkan).
3. 3.Pilih Bandingkan.
4. 4.Tinjau tab Merusak, Peringatan, dan Kompatibel, lalu filter berdasarkan metode atau bagian.
5. 5.Pilih perubahan untuk melihat nilai sebelum dan sesudah serta alasan perubahan itu penting.
6. 6.Salin perubahan yang merusak untuk pull request, atau unduh laporan Markdown atau JSON untuk CI.

Permintaan dan respons dinilai dari arah yang berlawanan. Di sisi permintaan (yang dikirim klien), semua yang mempersempit apa yang diterima bersifat merusak: parameter atau properti wajib baru, nilai enum yang dihapus, tipe atau format yang berubah, nilai maksimum yang lebih rendah atau minimum yang lebih tinggi, pola baru, atau tipe konten yang dihapus. Di sisi respons (yang diterima klien), semua yang menghapus atau memperluas apa yang dibaca klien bersifat merusak atau berupa peringatan: properti atau status sukses yang dihapus, tipe yang berubah, nilai enum baru, atau properti wajib yang menjadi opsional. Endpoint yang dihapus, autentikasi baru, skema keamanan yang berubah, dan scope OAuth yang ditambahkan bersifat merusak. Perubahan deskripsi, ringkasan, judul, dan contoh termasuk perubahan dokumentasi dan disembunyikan kecuali Anda mengaktifkannya.

Perbandingan berjalan di browser Anda dengan mesin aturan bawaan; spesifikasi tidak pernah diunggah. Impor URL mengambil berkas langsung dari browser Anda tanpa cookie, jadi untuk server yang memblokir permintaan lintas asal, unggah atau tempel berkasnya. Setiap spesifikasi dapat berukuran hingga 5 MB. Berkas $ref eksternal dilaporkan tetapi tidak diambil. Server, callback, webhook, link, dan ekstensi vendor tidak dibandingkan, dan aturan ini menggambarkan perkiraan dampak pada klien, bukan jaminan: server yang ketat atau longgar dapat berperilaku berbeda.