Cara Validasi API Sesuai Spesifikasi Tanpa Dredd

Dredd memecahkan masalah nyata, dan memecahkannya dengan bersih. Anda mengarahkannya ke deskripsi API, dokumen OpenAPI, atau file API Blueprint, dan ke server yang sedang berjalan. Dredd membaca setiap contoh dalam deskripsi, menembakkan permintaan yang cocok ke backend langsung, dan memeriksa bahwa respons nyata sesuai dengan apa yang dijanjikan oleh spesifikasi. Jika spesifikasi Anda mengatakan GET /orders/{id} mengembalikan 200 dengan bidang id dan status, Dredd mengonfirmasi bahwa layanan yang berjalan benar-benar melakukannya. Spesifikasi berhenti menjadi dokumentasi yang diam-diam membusuk dan menjadi pengujian yang gagal dengan keras.

Ide itu, memvalidasi implementasi terhadap deskripsi API, adalah ide yang tepat. Pergeseran antara apa yang dikatakan spesifikasi dan apa yang dilakukan layanan adalah salah satu bug senyap paling mahal dalam pekerjaan API. Tim frontend membuat kode berdasarkan kontrak yang didokumentasikan, backend mengirimkan perubahan nama bidang, tidak ada yang memperbarui dokumen, dan kerusakan muncul di produksi. Dredd menangkap kelas kegagalan itu, dan selama bertahun-tahun Dredd telah menjadi alat open-source pilihan untuk melakukannya dari baris perintah.

Hambatannya ada pada pengaturan dan pemeliharaan, bukan konsepnya. Dredd adalah CLI Node.js yang membutuhkan file konfigurasinya sendiri, file kait (hooks) dalam bahasa pilihan Anda untuk apa pun selain kasus-kasus sepele, dan artefak spesifikasi terpisah yang Anda pelihara secara manual di samping yang lainnya. Jika Anda menginginkan hasil yang sama seperti yang Dredd berikan, yaitu gerbang CI yang gagal ketika implementasi Anda tidak lagi sesuai dengan kontrak OpenAPI-nya, tanpa menyiapkan toolchain kait dan tanpa menyimpan spesifikasi sebagai file ketiga yang terputus, Apidog dibangun untuk alur kerja tersebut. Apidog menyimpan spesifikasi, pengujian, dan validasi dalam satu proyek, dan menjalankan semuanya secara headless dari CLI npm. Panduan ini jujur tentang apa yang Dredd lakukan dengan baik, dan jelas tentang di mana jalur terintegrasi menang.

Apa yang Dredd lakukan dengan baik

Berikan Dredd penghargaan terlebih dahulu, karena Dredd memang mendapatkan reputasi itu.

Dredd menguji implementasi, bukan tiruan. Ini adalah intinya. Banyak alat memvalidasi bahwa file OpenAPI Anda terbentuk dengan baik, atau bahwa server tiruan berperilaku. Dredd melakukan sesuatu yang lebih sulit: Dredd mengenai backend aktual yang sedang berjalan dan memeriksa byte nyata yang kembali terhadap contoh yang didokumentasikan. Eksekusi Dredd yang berhasil berarti layanan yang Anda terapkan dan spesifikasi Anda setuju saat ini, bukan secara teori.

Dredd berbicara API Blueprint dan OpenAPI. Dredd tumbuh bersama API Blueprint, format deskripsi berbasis markdown, dan kemudian menambahkan dukungan OpenAPI 2 dan 3. Jika Anda memiliki file Blueprint lama atau dokumen Swagger, Dredd dapat membacanya tanpa langkah konversi.

Kait (hooks) yang tidak tergantung bahasa. Ketika loop permintaan-dan-bandingkan default tidak cukup, Anda memerlukan token autentikasi, Anda perlu menanamkan basis data sebelum pengujian, Anda perlu melewati transaksi, Dredd memungkinkan Anda menulis kait. Penangan kait berjalan di Node secara default, tetapi Dredd menyediakan dukungan protokol untuk kait di Python, Ruby, Go, PHP, Rust, dan lainnya. Tim Anda menulis logika pengaturan dalam bahasa yang sudah mereka kenal.

Dredd adalah sumber terbuka dan ramah CI. Dredd diinstal dengan npm install -g dredd, berjalan sebagai satu perintah, dan keluar non-nol ketika validasi gagal, sehingga sistem CI apa pun dapat mengunci build berdasarkan itu. Tidak ada akun SaaS, tidak ada harga kursi, tidak ada yang perlu ditandatangani. Bagi tim yang menginginkan pemeriksaan kontrak yang dihosting sendiri dan dapat diskrip, itu penting.

Tidak ada yang sekadar pengisi. Dredd adalah alat yang solid dengan tugas yang jelas. Pertanyaannya adalah apakah modelnya, tiga artefak terpisah dan satu file kait, cocok dengan cara Anda benar-benar ingin bekerja.

Di mana letak hambatannya

Tiga biaya datang dengan model Dredd, dan seberapa besar dampaknya tergantung pada pengaturan Anda.

Spesifikasi adalah artefak ketiga yang Anda pelihara secara manual. Dredd memvalidasi implementasi terhadap file deskripsi, yang sepenuhnya benar, tetapi deskripsi itu biasanya hidup terpisah dari tempat Anda mendesain dan menguji API. Anda mengedit openapi.yaml secara manual, Anda menyimpan skenario pengujian Anda di tempat lain, dan Anda menyimpan layanan yang berjalan di tempat lain lagi. Dredd memeriksa dua dari tiga hal tersebut satu sama lain. Menjaga spesifikasi itu sendiri tetap akurat masih merupakan tugas manual, dan spesifikasi yang diam-diam menyimpang dari kenyataan menghasilkan eksekusi Dredd yang berwarna hijau dan salah.

Kait (hooks) adalah kode yang Anda tulis dan pelihara. Saat API Anda membutuhkan autentikasi, pengurutan, atau data pengujian, loop berbasis contoh tidak lagi cukup. Anda menulis hooks.js (atau padanan Python atau Ruby), menghubungkannya melalui dredd.yml, dan sekarang Anda memiliki basis kode kedua yang satu-satunya tugasnya adalah membuat yang pertama dapat diuji. Untuk API baca-saja sederhana, Dredd hampir bebas konfigurasi. Untuk yang nyata dengan login dan titik akhir stateful, file kait tumbuh, dan itu adalah kode perekat dengan nama lain.

Cakupan berbasis contoh memiliki celah. Dredd menguji contoh yang ada dalam deskripsi Anda. Jika sebuah titik akhir memiliki satu contoh respons yang didokumentasikan, itulah yang diperiksa. Kasus-kasus khusus, jalur kesalahan, dan aturan validasi yang tidak dijelaskan sebagai contoh dalam spesifikasi tidak akan dijalankan kecuali Anda menambahkannya, dengan memperluas spesifikasi atau dengan menulis lebih banyak kait.

Jalur terintegrasi: spesifikasi dan pengujian dalam satu proyek

Inilah taruhan berbeda yang dibuat Apidog. Definisi API bukanlah file ketiga yang Anda sinkronkan secara manual; itu adalah sumber kebenaran yang hidup dalam proyek yang sama dengan pengujian yang menjalankannya dan validasi yang mengunci build Anda. Ubah skema, dan pengujian melihat bentuk baru. Tidak ada openapi.yaml terpisah yang menyimpang di sudut repo, dan tidak ada file kait yang berdiri di antara spesifikasi dan pengujian yang berfungsi.

Anda mendesain atau mengimpor API sekali. Apidog membaca OpenAPI 2 dan 3, mengimpor dokumen Swagger, dan menarik koleksi Postman dalam satu klik. Titik akhir, skema permintaan, skema respons, dan contoh respons semuanya berada dalam satu proyek. Jika Anda sudah berpikir spec-first, ini adalah disiplin yang sama yang Dredd dorong, hanya saja tanpa spesifikasi menjadi file lepas. Versi yang lebih dalam dari alur kerja itu ada dalam pengembangan API spec-first, dan jika Anda ingin memvalidasi dokumen spesifikasi itu sendiri sebelum pengujian apa pun berjalan, memvalidasi spesifikasi OpenAPI mencakup langkah tersebut.

Anda membangun validasi terhadap skema nyata tersebut. Ketika skenario pengujian memanggil GET /orders/{id}, Anda menegaskan respons terhadap skema yang sudah dimiliki Apidog untuk titik akhir itu, bukan terhadap contoh yang disalin secara manual. Itu adalah pemeriksaan spesifikasi-versus-implementasi yang dilakukan Dredd, dengan satu perbedaan: spesifikasi yang diperiksa adalah objek yang sama dengan yang Anda rancang API-nya, sehingga tidak dapat secara diam-diam menyimpang dari rangkaian pengujian Anda. Ini adalah pengujian kontrak tanpa artefak ketiga, dan jika Anda ingin gambaran yang lebih luas tentang disiplin itu, pengujian kontrak API dan pengujian kontrak bidireksional keduanya membahas lebih dalam.

Pengaturan yang Dredd tangani dengan file kait, token autentikasi, pengurutan, penanaman, Anda tangani dengan skrip pra- dan pasca-permintaan dalam JavaScript, yang sudah ditulis oleh sebagian besar pengembang web. Tidak ada basis kode kait terpisah yang dihubungkan melalui file konfigurasi. Logika hidup di samping pengujian yang didukungnya.

Menginstal dan menjalankan Apidog CLI

Runner dipublikasikan ke npm sebagai apidog-cli. Jika Anda memiliki Node.js, Anda memiliki semua yang Anda butuhkan:

npm install -g apidog-cli

Biner tersebut adalah apidog, jadi setiap eksekusi dimulai dengan apidog run. Untuk menjalankan skenario pengujian, Anda meneruskan token akses, ID skenario, dan ID lingkungan:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Anda tidak mengetik ID tersebut secara manual. Buka skenario pengujian di Apidog, buka tab CI/CD-nya, pilih opsi baris perintah, dan hasilkan token akses. Apidog membangun perintah apidog run lengkap untuk Anda dengan ID skenario dan lingkungan yang sudah terisi. Salin sekali dan parameterisasi token dari sana. Perlakukan token akses seperti kata sandi: simpan sebagai rahasia di sistem CI Anda dan rujuk sebagai $APIDOG_ACCESS_TOKEN, seperti yang dilakukan setiap contoh di sini.

Untuk menjalankan lebih dari satu skenario, arahkan runner ke folder atau test suite daripada satu ID, dan pilih pelapor Anda:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

Bendera -r itu memilih pelapor. Apidog mendukung cli untuk output terminal yang dapat dibaca, html untuk laporan mandiri yang Anda arsipkan sebagai artefak build, junit untuk XML yang hampir setiap dasbor CI mengurai menjadi pohon pass/fail, dan json untuk hasil terstruktur mentah. Jika Anda ingin tur lebih dalam tentang runner, jalankan apidog run --help untuk daftar bendera lengkap.

Perbandingan

Baca tabel itu dengan jujur. Jika Anda menginginkan alat yang sepenuhnya dihosting sendiri, sumber terbuka, tanpa akun, dan tim Anda nyaman memelihara file kait, model Dredd sangat cocok dan beralih demi itu sendiri tidak memberi Anda apa-apa. Kasus untuk jalur terintegrasi bersifat spesifik: Anda bosan spesifikasi menjadi file ketiga yang menyimpang, Anda tidak ingin memiliki basis kode kait, atau Anda ingin proyek yang sama menangani desain, pengujian, dan pemeriksaan kontrak secara bersamaan.

Menghubungkannya ke CI

Apidog CLI keluar nol saat berhasil dan bukan nol saat gagal, sehingga sistem CI apa pun dapat mengunci build dengannya, sama seperti Dredd. Sebuah pekerjaan GitHub Actions minimal membutuhkan Node dan satu langkah run:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Itulah seluruh pipeline. Pekerjaan Dredd terlihat serupa, instal CLI, jalankan satu perintah, tetapi Anda juga mengarahkannya ke file spesifikasi dan file kait Anda, dan Anda menjaga keduanya tetap terkini. Validasi berjalan dengan cara yang sama; perbedaannya adalah berapa banyak artefak yang Anda pertahankan untuk sampai ke sana.

Jika alasan Anda menggunakan Dredd adalah untuk menjaga spesifikasi dan layanan tetap jujur satu sama lain, logika yang sama muncul di alat lain. Tim mengalaminya dengan Swagger dan Postman yang menyimpang, yang dibahas dalam pengujian berbasis OpenAPI terhadap penyimpangan Swagger dan Postman, dan toko Java mengalaminya dengan Rest Assured, di mana cerita alternatifnya serupa: alat yang kuat yang modelnya menambahkan lapisan yang mungkin tidak Anda inginkan. Anda juga dapat menjalankan Apidog dari editor Anda dengan ekstensi VS Code jika Anda tidak ingin meninggalkan IDE Anda.

FAQ

Apakah Apidog pengganti langsung untuk pengaturan Dredd? Tidak, dan itu tidak berpura-pura menjadi demikian. Tidak ada pengonversi yang membaca dredd.yml dan hooks.js Anda dan menghasilkan skenario Apidog. Anda mengimpor spesifikasi OpenAPI Anda dan membangun kembali validasi di editor visual. Keuntungannya adalah Anda berhenti memelihara file kait dan spesifikasi yang longgar; biayanya adalah pembangunan kembali sekali. Jika Anda memiliki suite Dredd yang besar dan matang yang berfungsi, pembangunan kembali itu adalah keputusan nyata, bukan makan siang gratis.

Apakah Apidog memvalidasi implementasi langsung, seperti yang Dredd lakukan? Ya. CLI menembakkan permintaan nyata ke layanan Anda yang sedang berjalan dan menegaskan respons aktual terhadap skema dalam proyek Anda. Itu adalah pemeriksaan spesifikasi-versus-implementasi yang sama yang dilakukan Dredd. Perbedaannya adalah bahwa skema yang diperiksa adalah skema yang Anda rancang API-nya, sehingga tidak menyimpang dari pengujian Anda.

Bisakah saya tetap menangani autentikasi dan pengaturan pengujian seperti yang dilakukan kait Dredd? Ya. Apidog mendukung skrip pra-permintaan dan pasca-permintaan dalam JavaScript, sehingga Anda dapat mengambil token autentikasi, menanamkan data, mengubah payload, atau membangun pernyataan dinamis dalam kode. Logika tersebut berada dalam skenario yang didukungnya, bukan dalam file kait terpisah yang dihubungkan melalui konfigurasi.

Apakah Dredd melakukan sesuatu yang tidak dilakukan Apidog? Beberapa hal. Dredd sepenuhnya dihosting sendiri dan sumber terbuka tanpa akun, dan secara asli membaca API Blueprint, format deskripsi markdown yang lebih lama. Jika alat tanpa akun, sepenuhnya lokal, atau file Blueprint lama merupakan pusat pengaturan Anda, pertimbangkan hal itu dengan cermat sebelum beralih.

Format apa yang dibaca Apidog? OpenAPI 2 dan 3, dokumen Swagger, dan koleksi Postman, semuanya dapat diimpor ke dalam satu proyek. Jika Anda ingin memahami perbedaan format terlebih dahulu, Swagger versus OpenAPI dan gambaran umum spesifikasi OpenAPI keduanya menjelaskannya.

Intinya

Dredd mendapatkan ide inti dengan benar: deskripsi API Anda harus menjadi sesuatu yang Anda uji layanan yang sedang berjalan, bukan dokumen yang menyimpang. Jika Anda menginginkan CLI yang dihosting sendiri, sumber terbuka, dan Anda senang memelihara file spesifikasi dan file kait, Dredd adalah pilihan yang tepat dan Anda harus terus menggunakannya.

Jalur terintegrasi adalah untuk kasus di mana pemeliharaan itu adalah bagian yang ingin Anda hilangkan. Apidog menyimpan spesifikasi, pengujian, dan validasi dalam satu proyek, sehingga kontrak yang Anda periksa adalah kontrak yang sama dengan yang Anda rancang, dan Apidog menjalankan semuanya dari apidog run tanpa basis kode kait untuk dimiliki. Unduh Apidog dan impor file OpenAPI Anda yang sudah ada untuk melihat pemeriksaan spesifikasi-versus-implementasi berjalan dari satu perintah.