Pemvalidan Spesifikasi OpenAPI Menangkap Kesalahan di File Swagger Anda Sebelum Klien Tersesat

Spesifikasi OpenAPI adalah kontrak antara API Anda dan semua hal yang mengonsumsi API tersebut — klien otomatis, server mock, dokumentasi, dan kerangka kerja pengujian. Masalahnya adalah bahwa berbeda dengan kode aplikasi, spesifikasi yang rusak tidak menimbulkan pengecualian. Ia secara diam-diam menghasilkan output yang salah di bagian bawah, dan pertama kali Anda mendengar tentang hal ini adalah ketika klien SDK menghasilkan kode yang tidak dapat digunakan atau dokumen Anda menampilkan endpoint yang hilang.

Mendeteksi kesalahan spesifikasi sejak dini — sebelum mencapai konsumen — merupakan tugas dari validasi spesifikasi. Artikel ini membahas apa yang harus divalidasi, di mana kesalahan umum tersembunyi, dan bagaimana menjalankan validasi secara lokal dan di browser.

Mengapa Format Spesifikasi Anda Penting Lebih Dari Hanya Dokumentasi

Sebagian besar pengembang memandang spesifikasi OpenAPI sebagai artefak dokumentasi — sesuatu yang memicu Swagger UI atau Redoc. Itu hanya setengah dari gambaran. Spesifikasi juga merupakan sumber kebenaran untuk:

• Penghasilan kode — Alat seperti openapi-generator dan swagger-codegen menghasilkan stub server dan library klien secara langsung dari spesifikasi. Skema yang tidak benar menghasilkan kode yang tidak benar.
• Pengujian kontrak — Kerangka kerja seperti Dredd dan Schemathesis menguji API Anda secara langsung terhadap spesifikasi. Spesifikasi yang tidak valid berarti uji coba gagal dijalankan atau menghasilkan hasil yang salah.
• Server mock — Alat seperti Prism dan yang serupa menyajikan respons mock berdasarkan nilai contoh dan skema spesifikasi Anda. Skema yang salah menghasilkan mock yang salah.
• Konfigurasi gateway — AWS API Gateway, Kong, dan lainnya dapat mengimpor spesifikasi OpenAPI untuk mengatur routing, autentikasi, dan validasi. Spesifikasi yang tidak valid secara diam-diam mengabaikan atau mengonfigurasi salah rute.

Tidak ada alat ini yang akan memberi tahu Anda bahwa spesifikasi salah secara manusia yang mudah dimengerti. Mereka akan mengalami kegagalan, menghasilkan sampah, atau secara diam-diam melewatkan bagian yang terpengaruh. Validasi spesifikasi Anda sebelum mencapai konsumen ini tidak bisa diperdebatkan.

OpenAPI 2.0 vs 3.0 vs 3.1: Perbedaan Versi yang Menyebabkan Kesalahan pada Pengguna

Versi yang Anda deklarasikan di bagian atas spesifikasi mengubah aturan yang berlaku — dan banyak kesalahan berasal dari kekeliruan konvensi antar versi.

• OpenAPI 2.0 (Swagger) — Menggunakan swagger: "2.0". Isi permintaan dimasukkan ke parameters dengan in: body. Definisi berada di definitions, bukan components/schemas. Tidak mendukung oneOf, anyOf, atau not di tingkat skema.
• OpenAPI 3.0.x — Menggunakan openapi: "3.0.x". Isi permintaan pindah ke requestBody. Skema terkonsolidasi di bawah components. Mendukung oneOf, anyOf, allOfdan not. Menambahkan links dan callbacks.
• OpenAPI 3.1.0 — Tepat dengan JSON Schema draft 2020-12. nullable diganti oleh type: [string, null]. exclusiveMinimum/exclusiveMaximum perubahan dari tipe boolean menjadi tipe angka. $schema sekarang diizinkan dalam skema.

Kesalahan migrasi paling umum: menyalin spesifikasi 2.0 dan mengubah field versi menjadi 3.0.0 tanpa memindahkan isian permintaan dari parameters ke requestBody. Spesifikasi tampak valid dalam JSON/YAML tetapi gagal dalam validasi semantik.

Kesalahan Umum Spesifikasi dan Di mana Mereka Tersembunyi

Kesalahan spesifikasi jatuh ke pola yang dapat diprediksi. Berikut adalah yang paling sering muncul dalam kode aktual:

Kehilangan Field Wajib

Setiap operasi harus memiliki setidaknya satu respons 2xx yang didefinisikan. Setiap parameter membutuhkan name dan nilai in . Parameter jalur yang didefinisikan di URL (misalnya /users/{id}) harus memiliki objek parameter yang sesuai dengan in: path dan required: true. Kehilangan salah satunya menghasilkan spesifikasi yang secara teknis dapat diparsing, tetapi menghancurkan validator dan generator kode di bagian bawah.

Jalur $ref yang Tidak Valid

A $ref yang menunjuk ke komponen yang tidak ada merupakan salah satu bug spesifikasi paling umum. Referensi tampak valid — $ref: "#/components/schemas/UserProfile" — tetapi skema target diubah atau dihapus. Pemisah JSON/YAML menerima ini tanpa komentar. Hanya validator spesifikasi yang menangkapnya.

Luar $ref jalur bahkan lebih berisiko — mereka menunjuk ke file atau URL lain yang mungkin tidak dapat diakses di setiap lingkungan. Sisipkan referensi ini sebelum Anda mendistribusikan spesifikasi atau menggunakan alat yang tidak menyelesaikan eksternal.

Tipe Skema yang Salah

Kesalahan tipe skema sangat halus. Menyatakan type: integer pada field yang mengembalikan nilai float. Menggunakan format: date-time dengan field yang mengembalikan timestamp Unix (angka). Mendefinisikan enum dengan nilai yang tidak sesuai dengan yang dideklarasikan type. Hal ini lolos parsing YAML tetapi menghasilkan properti yang salah dalam klien yang dihasilkan.

Referensi Lingkaran

Skema yang merujuk pada dirinya sendiri — secara langsung atau melalui rantai nilai $ref — menyebabkan generator kode dan alat dokumentasi berputar tanpa henti atau crash. Sebagian besar validator mendeteksi dan melaporkan referensi lingkaran, tetapi bisa sulit dipecahkan dalam skema yang sangat terkait. Solusi biasanya adalah memecah siklus dengan skema khusus untuk kasus rekursif.

Kesalahan Struktural vs Semantik

Kesalahan validasi tidak semuanya sama. Memahami perbedaan ini membantu Anda memprioritaskan perbaikan:

• Kesalahan struktural — Spesifikasi tidak sesuai dengan skema OpenAPI. Field wajib hilang, nama properti salah, atau tipe tidak sesuai dengan format spesifikasi. Kesalahan ini ditangkap oleh validasi skema ketat dan menghentikan kebanyakan alat.
• Kesalahan semantik — Spesifikasi secara struktural valid dalam JSON/YAML dan lolos validasi skema, tetapi menggambarkan sesuatu yang tidak bisa berjalan. Endpoint dengan parameter jalur di URL tetapi tidak ada definisi parameter. Skema respons menggunakan allOf dengan field wajib yang bertentangan. Kesalahan ini ditangkap oleh aturan linting yang lebih dalam, bukan oleh pemeriksaan skema dasar.

Sebagian besar validator online dan alat CLI dasar menangkap kesalahan struktural. Menangkap kesalahan semantik membutuhkan linter berbasis aturan seperti Spectral, yang mengevaluasi logika dan konsistensi spesifikasi.

components/schemas: Definisi DRY vs Skema Inline

OpenAPI 3.0 memperkenalkan components/schemas sebagai tempat resmi untuk mendefinisikan skema yang dapat digunakan ulang. Kompromi:

• Skema yang dibagikan di komponen — Benar ketika skema yang sama muncul di beberapa tempat (misalnya, objek yang dikembalikan oleh beberapa endpoint). Menggunakan User membuat spesifikasi DRY dan menghasilkan satu kelas bernama dalam klien SDK. $ref: "#/components/schemas/User" menjaga spesifikasi tetap DRY dan menghasilkan satu kelas bernama dalam SDK klien.
• Skema inline — Benar untuk bentuk respons sementara yang hanya digunakan oleh satu endpoint dan tidak akan digunakan ulang. Menyisipkan menghindari memencet components/schemas dengan definisi sementara yang membuat spesifikasi lebih sulit dibaca.

Polanya yang buruk adalah mendefinisikan skema di components/schemas dan kemudian tidak merujuk kepadanya. Validator seperti Spectral dapat menandai komponen yang tidak digunakan, yang sering menunjukkan bahwa $ref yang seharusnya merujuk kepadanya tetapi menunjuk ke tempat lain.

requestBody vs parameters: Di mana Hal-Hal Salah Terjadi

Di OpenAPI 3.0, isian permintaan dan parameter dibagi secara ketat:

• parameter — Untuk nilai jalur, query, header, dan cookie. Setiap parameter adalah nilai skalar, bukan objek kompleks.
• requestBody — Untuk isian permintaan (badan JSON, data form, upload file). Wajib untuk operasi POST/PUT/PATCH yang menerima badan.

Kesalahan yang mengecoh pengembang saat beralih dari 2.0: di Swagger 2.0, isian permintaan adalah parameter dengan in: body. Di OpenAPI 3.0 itu tidak valid — in: body tidak ada. Spesifikasi dengan in: body lulus parsing YAML tetapi gagal dalam validasi spesifikasi, dan generator kode mengalami kesalahan atau secara diam-diam melewatkan isian permintaan.

Cara Memvalidasi Spesifikasi Anda Secara Lokal

Tiga alat CLI yang kuat untuk validasi lokal, dari yang paling sederhana hingga yang paling menyeluruh:

swagger-cli

Validasi struktural cepat dan $ref resolusi. Cocok untuk pengecekan kecepatan:

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

Melaporkan kesalahan struktural dan jalur yang rusak. $ref Tidak menangkap masalah semantik atau masalah gaya.

Redocly CLI

Validasi struktural ditambah setelan aturan yang dapat dikonfigurasi. Cocok untuk ketatnya standar produksi:

npm install -g @redocly/cli
redocly lint openapi.yaml

Menangkap kehilangan deskripsi, referensi yang rusak, dan banyak masalah semantik secara otomatis.

Spectral

Linter yang paling dapat dikonfigurasi. Menjalankan aturan bawaan OpenAPI ditambah aturan yang Anda definisikan. Ideal untuk tim yang ingin mengenakan panduan gaya API internal:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Spectral membedakan kesalahan (yang menghancurkan spesifikasi) dari peringatan (masalah gaya/kepenuhan), sehingga Anda dapat memperbaiki masalah yang menghambat terlebih dahulu tanpa gangguan dari aturan saran.

Memvalidasi di Browser Tanpa Menginstal Apapun

Jika Anda ingin memvalidasi spesifikasi dengan cepat — tanpa mengatur CLI atau menjalankan build — alat OpenAPI / Swagger Spec Validator di iotools.cloud berjalan sepenuhnya di browser. Tempel spesifikasi YAML atau JSON Anda dan ia melaporkan kesalahan struktural, jalur yang rusak, kehilangan field wajib, dan masalah versi khusus di OpenAPI 2.0, 3.0, dan 3.1. $ref Alat ini berguna untuk pengecekan cepat sebelum mengirimkan, untuk memeriksa spesifikasi yang dikirim oleh orang lain, atau untuk memverifikasi spesifikasi yang dihasilkan dari annotasi sebelum menjalankan generasi kode.

Membangun Validasi ke dalam Alur Kerja Anda

Validasi satu kali menangkap masalah segera tetapi tidak mencegah regresi. Pendekatan yang lebih tahan lama:

Hook sebelum commit

• — Jalankan sebelum setiap commit. Spesifikasi yang rusak tidak pernah mencapai repositori. swagger-cli validate atau spectral lint sebelum setiap commit. Spesifikasi yang rusak tidak pernah mencapai repositori.
• Langkah dalam pipeline CI — Tambahkan validasi spesifikasi sebagai langkah awal dalam pipeline CI, sebelum langkah apa pun yang menghasilkan kode atau deploy yang bergantung pada spesifikasi.
• Validasi spesifikasi yang dihasilkan — Jika Anda menghasilkan spesifikasi dari annotasi kode (misalnya, springdoc, swagger-annotations, FastAPI), validasi output yang dihasilkan, bukan hanya annotasi. Langkah penghasilan sendiri dapat menghasilkan output yang tidak valid ketika annotasi bertentangan atau tidak lengkap.

Tujuannya adalah membuat spesifikasi yang tidak valid tidak dapat dikirim — bukan hanya sesuatu yang diperbaiki ketika konsumen melaporkan masalah.

Anda mungkin juga menyukai