Swagger CLI: Validasi, Linting, dan Uji Spesifikasi API dari Terminal

Anda membuka permintaan tarik (pull request), dokumentasi berhasil dibuat, dan tiga hari kemudian rekan tim mengingatkan Anda: server staging menolak setiap permintaan karena file OpenAPI memiliki `$`ref` yang menggantung yang mengarah ke jalur yang Anda ganti namanya. Spesifikasi terlihat benar di editor. Itu dirender di Swagger UI. Namun, itu sebenarnya tidak valid, dan tidak ada dalam pipeline Anda yang menangkapnya sebelum dikirim.

Itulah persisnya pekerjaan yang dibuat untuk alat baris perintah Swagger: menangkap spesifikasi yang rusak sebelum manusia melakukannya. Frasa "swagger cli" biasanya merujuk pada `@apidevtools/swagger-cli`, sebuah paket npm kecil yang dua perintahnya, `validate` dan `bundle`, memeriksa dokumen OpenAPI dan menggabungkan spesifikasi multi-file menjadi satu. Ini adalah alat yang benar-benar berguna, dan panduan ini menunjukkan cara menggunakannya dengan benar. Ini juga menunjukkan di mana batasnya, karena memvalidasi spesifikasi hanyalah separuh pertama dari kepercayaan pada API; separuh kedua adalah mengirimkan permintaan nyata dan menegaskan apa yang kembali, dan di situlah runner seperti Apidog CLI mengambil alih.

tombol

Jadi ini sebenarnya adalah pekerjaan dua terminal. Pertama, lint dan gabungkan spesifikasi dengan `swagger-cli` (atau penerusnya) agar kontraknya valid. Kemudian jalankan tes aktual terhadap API yang berjalan dari baris perintah agar Anda tahu implementasi cocok dengan kontrak. Kami akan membahas keduanya, jujur tentang alat mana yang melakukan pekerjaan apa, dan memberi Anda perintah siap pakai untuk masing-masing.

Apa yang sebenarnya dimaksud dengan "swagger cli"

Tidak ada satu pun biner resmi yang disebut "swagger." Nama tersebut merujuk pada beberapa alat yang berbeda, dan mengetahui alat mana yang Anda maksud akan menghemat banyak kebingungan.

@apidevtools/swagger-cli adalah paket yang paling sering dimaksud orang. Binernya adalah `swagger-cli`, dan ia melakukan dua hal: memvalidasi dokumen OpenAPI atau Swagger 2.0, dan menggabungkan spesifikasi multi-file menjadi satu file. Ini adalah fokus paruh pertama artikel ini.
swagger-codegen adalah proyek SmartBear yang terpisah dan jauh lebih besar yang menghasilkan SDK klien dan stub server dari spesifikasi. Pekerjaan yang sama sekali berbeda; kami akan membahasnya di bagian akhir.
Swagger UI dan Swagger Editor sama sekali bukan CLI. Mereka merender dan mengedit spesifikasi di browser. Jika Anda masih mempelajari formatnya, panduan dasar Swagger dan OpenAPI adalah titik awal yang tepat.

Panduan ini adalah tentang pekerjaan baris perintah: memvalidasi, menggabungkan (bundling), melinting, dan kemudian menguji. Jika Anda menginginkan survei yang lebih luas tentang platform desain dan pengujian, ringkasan alternatif Swagger mencakup sisi GUI.

Menginstal swagger-cli

Alat ini dikirim sebagai paket npm. Instal secara global:

npm install -g @apidevtools/swagger-cli

Konfirmasi instalasi berhasil:

swagger-cli --version
swagger-cli --help

Node.js adalah satu-satunya dependensi sistem. Setiap mesin atau image CI yang sudah menginstal Node dapat menjalankannya. Jika Anda tidak ingin menginstalnya secara global, Anda dapat memanggilnya sesuai permintaan dengan `npx @apidevtools/swagger-cli ...`, yang berguna pada build runner yang bersifat sementara.

Satu hal yang perlu diketahui sebelum Anda mengandalkannya: pengelola telah menandai `swagger-cli` sebagai tidak digunakan lagi (deprecated). README menyatakannya dengan jelas, mengutip beban pemeliharaan basis pengguna yang besar dengan sedikit kontributor. Ini masih berfungsi, dan banyak pipeline menjalankannya hari ini, tetapi proyek-proyek baru diarahkan ke Redocly CLI sebagai penerus yang aktif dipelihara. Kami akan membahas migrasi tersebut di bagiannya sendiri di bawah, sehingga Anda dapat memutuskan dengan pemahaman penuh.

Memvalidasi spesifikasi dengan swagger-cli

Perintah utama adalah `validate`. Arahkan ke file spesifikasi Anda:

swagger-cli validate openapi.yaml

Jika dokumen valid, Anda akan mendapatkan konfirmasi satu baris dan kode keluar `0`. Jika ada yang salah, Anda akan mendapatkan kesalahan yang menjelaskan masalah dan kode keluar bukan nol, yang persis seperti yang Anda inginkan dalam pipeline.

`validate` menjalankan dua pemeriksaan di balik layar, dan Anda dapat mematikan salah satunya:

swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml

`--no-schema` melewati validasi terhadap Skema JSON OpenAPI, yaitu pemeriksaan struktural yang mengonfirmasi bahwa dokumen Anda memiliki bentuk yang benar. `--no-spec` melewati validasi terhadap aturan spesifikasi itu sendiri, yaitu pemeriksaan semantik yang menangkap hal-hal seperti ID operasi duplikat atau `$ref` yang tidak menunjuk ke mana-mana. Sebagian besar waktu Anda ingin keduanya aktif, yang merupakan pengaturan default. Flag ini ada untuk kasus langka di mana satu lapisan menandai sesuatu yang Anda sengaja ingin izinkan.

Apa yang ditangkap dengan baik oleh `validate`: YAML yang salah format, field wajib yang hilang, pointer `$ref` yang rusak, dan kesalahan struktural yang membuat spesifikasi tidak dapat diurai. Apa yang tidak dilakukannya adalah menegakkan gaya tim Anda. Ini akan dengan senang hati meluluskan spesifikasi tanpa deskripsi, penamaan yang tidak konsisten, dan tanpa contoh, karena tidak ada hal tersebut yang melanggar aturan OpenAPI. Untuk jenis pemeriksaan berpendapat seperti itu, Anda memerlukan linter, yang merupakan bagian selanjutnya.

Jika validasi adalah satu-satunya tujuan Anda, panduan mendalam tentang cara memvalidasi spesifikasi OpenAPI membandingkan beberapa alat dan kasus khusus yang perlu diketahui.

Menggabungkan spesifikasi multi-file

Spesifikasi nyata jarang berada dalam satu file. Anda memisahkan skema ke dalam direktori `components/`, mereferensikannya dengan `$ref`, dan menjaga agar file root mudah dibaca. Itu adalah praktik yang baik, tetapi banyak alat hilir menginginkan dokumen tunggal yang mandiri. Perintah `bundle` meratakan struktur tersebut:

swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml

Flag yang perlu diketahui:

-o, --outfile <file> menulis hasil ke file alih-alih mencetaknya ke stdout.
-t, --type <json|yaml> mengatur format output. Defaultnya adalah json, jadi teruskan -t yaml jika Anda menginginkan output YAML.
-r, --dereference sepenuhnya menyertakan setiap $ref alih-alih hanya mengumpulkan file eksternal menjadi satu dokumen. Ini menghasilkan file yang lebih besar tanpa referensi yang tersisa, yang mungkin diperlukan oleh beberapa konsumen.
-f, --format <spaces> mengontrol indentasi, defaultnya 2 spasi.
-w, --wrap <column> mengatur panjang baris untuk membungkus string YAML yang panjang.

Perbedaan antara bundle biasa dan `--dereference` itu penting. Bundle normal mempertahankan pointer `$ref` internal tetapi menarik semua file terpisah menjadi satu, sehingga dokumen dapat dipindahkan. `--dereference` menyelesaikan setiap referensi menjadi objek inline, yang memperbesar ukuran file tetapi menjamin tidak ada konsumen yang harus menyelesaikan pointer. Gunakan bundle biasa untuk distribusi dan bentuk yang sudah dideferensikan hanya ketika alat tertentu memintanya.

Pola umum adalah memvalidasi dan menggabungkan dalam satu langkah sebagai bagian dari build:

swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json

Simbol `&&` berarti bundling hanya berjalan jika validasi berhasil, sehingga spesifikasi yang rusak tidak akan pernah menghasilkan artefak build.

Mengintegrasikan swagger-cli ke dalam CI

Validasi paling berharga ketika dijalankan pada setiap perubahan, bukan ketika seseorang mengingatnya. Masukkan ke dalam pipeline Anda sebagai gerbang cepat. Berikut adalah langkah GitHub Actions yang akan menggagalkan build jika spesifikasi tidak valid:

name: Validate OpenAPI spec

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'components/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate spec
        run: npx @apidevtools/swagger-cli validate openapi.yaml

Karena `swagger-cli validate` keluar dengan kode bukan nol pada spesifikasi yang buruk, langkah tersebut akan menjadi merah dan permintaan tarik akan menampilkan pemeriksaan yang gagal. Tidak ada konfigurasi tambahan. Filter `paths` mencegah pekerjaan berjalan ketika spesifikasi tidak berubah, yang menghemat menit CI Anda.

Ini adalah gerbang kualitas termurah yang dapat Anda tambahkan ke repositori API. Ini hanya memakan waktu beberapa detik dan menghentikan seluruh kelas bug "dokumentasi berbohong" agar tidak mencapai siapa pun di hilir.

Saat Anda memerlukan linting, bukan hanya validasi

Validasi menjawab satu pertanyaan: apakah ini dokumen OpenAPI yang sah? Linting menjawab pertanyaan yang lebih sulit: apakah ini dokumen OpenAPI yang baik menurut standar tim kami? Keduanya tidak sama, dan `swagger-cli` hanya melakukan yang pertama.

Misalnya, panduan gaya Anda mengharuskan setiap operasi memiliki `summary`, setiap properti memiliki `description`, dan setiap jalur menggunakan kebab-case. Spesifikasi dapat melanggar ketiganya dan tetap lulus `swagger-cli validate`, karena tidak ada aturan tersebut yang merupakan bagian dari spesifikasi OpenAPI. Linter memungkinkan Anda untuk mengodekan dan menegakkan aturan tersebut.

Ini adalah alasan utama tim beralih ke Redocly CLI, penerus yang dipelihara yang ditunjukkan oleh `swagger-cli` itu sendiri. Ini mencakup validasi dan bundling yang sama, lalu menambahkan mesin linting sungguhan di atasnya.

Migrasi ke Redocly CLI

Migrasinya kecil karena nama perintahnya mirip. Instal penerusnya:

npm install -g @redocly/cli

Ekuivalen dengan `validate` adalah `lint`. Untuk mencocokkan perilaku lama, perluas set aturan minimal:

redocly lint --extends=minimal openapi.yaml

Jalankan dengan set aturan default dan itu akan menegakkan set aturan yang direkomendasikan yang lebih kuat, di situlah nilai linting muncul. Anda mengkonfigurasi aturan dalam file `redocly.yaml`, mengatur setiap aturan menjadi `error` atau `warn`, dan bahkan menulis plugin khusus untuk pemeriksaan khusus organisasi.

Bundling hampir sama persis:

redocly bundle openapi.yaml -o dist/openapi.yaml

Nama flag sedikit berubah. `-o/--outfile` pada `swagger-cli` menjadi `--output`, `-t/--type` menjadi `--ext`, dan `-r/--dereference` menjadi `-d/--dereferenced`. Jika skrip lama Anda menggunakan flag pendek, pencarian dan penggantian cepat akan membantu Anda. Untuk perbandingan alat pemeriksaan spesifikasi yang lebih luas, ulasan tentang alat validator OpenAPI terbaik menempatkan Redocly di samping alternatifnya.

Singkatnya: jika Anda memulai dari awal, gunakan Redocly CLI. Jika Anda memiliki langkah `swagger-cli` yang berfungsi, tidak ada masalah mendesak, tetapi jalur ke depan sudah jelas dan penggantian namanya bersifat mekanis.

Bagian yang tidak dapat dicakup oleh alat spesifikasi

Berikut adalah batasan setiap alat yang telah kita bahas sejauh ini. `swagger-cli validate` mengonfirmasi bahwa spesifikasi Anda terbentuk dengan baik. `redocly lint` mengonfirmasi bahwa spesifikasi tersebut mengikuti gaya Anda. Keduanya tidak mengirimkan satu pun permintaan ke API yang sedang berjalan. Spesifikasi bisa sempurna di atas kertas sementara implementasinya mengembalikan 500, menghilangkan bidang yang dijanjikan, atau sepenuhnya mengabaikan parameter kueri.

Menutup celah itu berarti pengujian fungsional: mengirimkan permintaan nyata ke endpoint nyata, lalu menegaskan kode status, badan respons, dan nilai-nilai di dalamnya. Itu adalah kategori alat yang berbeda, dan di sinilah Apidog sesuai dengan alur kerja.

Apidog adalah platform API all-in-one. Anda mengimpor spesifikasi OpenAPI Anda, dan dari satu definisi tersebut Anda mendapatkan dokumentasi interaktif, server mock, dan skenario pengujian yang dapat Anda rangkai dengan penegasan, semuanya tanpa meninggalkan ruang kerja. Impornya langsung; panduan tentang mengimpor Swagger atau OpenAPI dan menghasilkan permintaan yang dapat dijalankan menjelaskannya, dan Anda dapat menghasilkan koleksi tes lengkap langsung dari spesifikasi alih-alih membangunnya secara manual.

Bagian yang penting untuk terminal adalah command-line runner, yang diterbitkan sebagai paket npm `apidog-cli`. Anda menginstalnya dan menjalankan skenario yang disimpan secara headless:

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

Flag `-t` adalah ID skenario pengujian, `-e` adalah ID lingkungan, dan `-r` memilih format laporan seperti `cli`, `html`, `json`, atau `junit`. Seperti `swagger-cli`, ia keluar dengan kode status yang bersih, sehingga penegasan yang gagal akan membuat pipeline menjadi merah. Tidak seperti `swagger-cli`, yang diperiksanya adalah perilaku langsung API Anda, bukan hanya bentuk file yang menggambarkannya. Untuk referensi flag lengkap dan contoh CI, lihat panduan lengkap Apidog CLI, atau jalankan `apidog run --help` untuk opsi saat ini. Jika Anda ingin menyiapkan skenario pertama itu, unduh Apidog, impor spesifikasi Anda, dan perintah runner adalah satu salinan dari tab CI/CD skenario tersebut.

Alur kerja terminal yang lengkap

Satukan kedua bagian tersebut dan Anda akan mendapatkan pipeline yang memeriksa kontrak dan implementasi secara berurutan:

# 1. Apakah spesifikasinya terbentuk dengan baik dan sesuai gaya?
redocly lint --extends=minimal openapi.yaml

# 2. Hasilkan satu dokumen yang dapat didistribusikan.
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. Apakah API yang berjalan benar-benar cocok dengan kontrak?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

Langkah pertama akan cepat gagal pada spesifikasi yang salah format atau tidak sesuai gaya. Langkah kedua menghasilkan artefak yang dikonsumsi oleh dokumentasi dan generator SDK Anda. Langkah ketiga mengirimkan lalu lintas nyata dan menegaskan respons, sehingga build yang hijau berarti kontrak dan kode di belakangnya valid. Setiap langkah keluar dengan kode bukan nol pada kegagalan, sehingga seluruh rantai adalah satu gerbang yang dapat Anda masukkan ke runner CI mana pun yang memiliki Node.

Jika pengujian Anda hari ini bergantung pada alat kesesuaian spesifikasi yang sudah tidak aktif, tulisan tentang memvalidasi API terhadap spesifikasinya tanpa Dredd mencakup ide kontrak-versus-implementasi yang sama dari sudut yang berbeda.

Catatan tentang swagger-codegen

Orang-orang yang mencari "swagger cli" terkadang sebenarnya menginginkan `swagger-codegen`, yang merupakan alat yang berbeda dengan pekerjaan yang berbeda. Alat ini membaca spesifikasi OpenAPI dan menghasilkan SDK klien, stub server, dan dokumentasi dalam puluhan bahasa. Ini benar-benar berguna untuk bootstrapping klien bertipe dari spesifikasi yang diterbitkan, dan pantas disebut sebagai opsi pembuatan kode paling mumpuni dalam keluarga Swagger.

Ia tidak melakukan validasi, linting, atau pengujian dalam arti yang dibahas artikel ini. Generasi mengasumsikan Anda sudah memiliki spesifikasi yang valid; jika inputnya rusak, outputnya juga akan rusak dengan cara yang sesuai. Jadi, bahkan dalam alur kerja codegen, Anda tetap menginginkan langkah validasi atau linting di depannya. Alat-alat ini saling melengkapi daripada saling menggantikan.

tombol