Jika Anda datang ke sini setelah menjalankan npm install -g @apidevtools/swagger-cli dan menyadari adanya peringatan, berikut adalah versi singkatnya: alat ini tidak lagi dikelola. Repositori swagger-cli di GitHub dengan jelas menyatakan bahwa alat ini tidak digunakan lagi (deprecated), dengan alasan “beban pemeliharaan untuk mencoba memenuhi harapan basis pengguna yang besar dengan sedikit atau tanpa kontribusi.” README itu sendiri mengarahkan Anda ke Redocly CLI sebagai penggantinya.
Jadi, Anda memerlukan pengganti. Artikel ini secara khusus membahas alat terminal swagger-cli, yang melakukan validate dan bundle. Jika yang Anda maksud adalah Swagger Editor, SwaggerHub, atau rangkaian desain yang lebih luas, bacalah 7 alternatif Swagger yang juga menguji API Anda sebagai gantinya.
Mari kita lihat apa yang dilakukan swagger-cli, lalu kita akan membahas daftar singkat yang jujur tentang apa yang harus digunakan sekarang.
Apa yang sebenarnya dilakukan swagger-cli
Penting untuk bersikap tepat, karena pengganti yang tepat bergantung pada apa yang Anda gunakan.
swagger-cli hanya memiliki dua perintah:
# Memvalidasi definisi Swagger 2.0 / OpenAPI 3.0 terhadap skema dan memeriksa $refs
swagger-cli validate openapi.yaml
# Mengikuti pointer $ref dan menggabungkan definisi multi-file menjadi satu file
swagger-cli bundle openapi.yaml -o bundled.json
Perintah bundle memiliki beberapa opsi: -o/--outfile untuk menulis ke file, -t/--type untuk memilih JSON atau YAML, -r/--dereference untuk sepenuhnya menyisipkan setiap $ref, dan -f/--format untuk indentasi.
Itulah keseluruhan alatnya. Ia memvalidasi struktur dan menggabungkan spesifikasi multi-file. Ia tidak melakukan linting dengan aturan gaya, membuat dokumen, menjalankan tes, atau memalsukan apa pun. Jika Anda membaca klaim bahwa swagger-cli "melakukan linting" spesifikasi Anda, itu salah; ia hanya memeriksa definisi Anda terhadap skema OpenAPI dan menyelesaikan referensi. Ingatlah cakupan itu, karena beberapa pengganti melakukan jauh lebih banyak, dan Anda mungkin menginginkannya atau tidak.
Daftar singkat
Tiga alat mencakup hampir setiap alasan Anda menggunakan swagger-cli, ditambah beberapa spesialis yang patut disebutkan. Berikut adalah ringkasan yang jujur.
Redocly CLI: penerus resmi dan pengganti 1:1 terdekat
Redocly CLI (@redocly/cli, biner redocly) adalah sumber terbuka dan merupakan alat yang direkomendasikan oleh README swagger-cli sendiri. Redocly bahkan menerbitkan panduan migrasi dari swagger-cli. Jika tujuan Anda adalah validator dan bundler terminal yang langsung pakai, mulailah dari sini.
Instal dengan cara yang sama seperti Anda menginstal swagger-cli:
npm install -g @redocly/cli@latest
# atau jalankan tanpa instalasi
npx @redocly/cli@latest lint openapi.yaml
Pemetaannya jelas. validate swagger-cli menjadi redocly lint, yang memeriksa spesifikasi Anda dan menerapkan aturan gaya yang dapat dikonfigurasi. bundle swagger-cli menjadi redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Berikut adalah pemetaan flag bundle secara berdampingan:
| swagger-cli | Redocly CLI | Tujuan |
|---|---|---|
-o, --outfile |
--output (atau -o) |
Menulis ke file |
-t, --type |
--ext (json, yaml, yml) |
Format keluaran |
-r, --dereference |
-d, --dereferenced |
Menyisipkan sepenuhnya semua $ref |
Satu hal yang perlu diketahui: redocly lint melakukan lebih dari validate swagger-cli secara default. Ia menerapkan seperangkat aturan panduan gaya, bukan hanya pemeriksaan skema. Jika Anda menginginkan validasi struktural sederhana yang diberikan swagger-cli, konfigurasikan redocly.yaml hanya dengan aturan spec, lalu jalankan redocly lint openapi.yaml. Perilaku aturan tersebut adalah kekuatan khas Redocly, bukan kelemahan; inilah mengapa tim yang menginginkan tata kelola terminal-native menyukainya. Anda dapat menyetel seperangkat aturan (minimal, recommended, recommended-strict, spec) atau menulis aturan kustom. Lihat penyiapan linter OpenAPI terbaik untuk melihat bagaimana hal itu sesuai dengan linter lainnya.
Redocly CLI juga melampaui dua perintah swagger-cli. Ia dapat split deskripsi tunggal menjadi struktur multi-file (kebalikan dari bundle), join beberapa file (eksperimental), dan membangun dokumen HTML Redoc mandiri:
redocly build-docs openapi.yaml -o docs.html
Apa yang tidak dilakukannya: menjalankan tes API atau menghosting server mock. Ini adalah alat lint/bundle/docs yang mengutamakan kode, berbasis terminal, dan sangat baik. Jika hanya itu yang Anda butuhkan, Anda dapat berhenti membaca dan bermigrasi hari ini.
Apidog: ketika Anda menginginkan lebih dari validate plus bundle
Berikut adalah peninjauan ulang yang jujur. swagger-cli adalah skrip statis yang Anda jalankan untuk memvalidasi dan menggabungkan. Tetapi bagi sebagian besar tim, memvalidasi dan menggabungkan adalah sarana untuk mencapai tujuan. Anda memvalidasi agar spesifikasi benar, Anda menggabungkan agar portabel, dan kemudian Anda membuat mock-nya, mengujinya, dan mendokumentasikannya. swagger-cli menyerahkan langkah-langkah selanjutnya kepada alat lain.
Apidog menutup kesenjangan itu. Ini adalah platform API all-in-one: desain, mock, tes, dan dokumen dalam satu ruang kerja, dengan CLI yang menangani impor, ekspor, dan menjalankan tes CI. Di mana swagger-cli memberi Anda file, Apidog memberi Anda ruang kerja hidup yang dibangun dari file itu.
Dua perintah yang paling langsung memetakan ke memori otot swagger-cli Anda adalah import dan export. Instal CLI dan otentikasi terlebih dahulu:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
Anda mendapatkan token dari aplikasi Apidog atau web: avatar, lalu Pengaturan Akun, lalu Token Akses API. Token tersebut disimpan di ~/.apidog/config.toml, jadi jangan pernah mencetaknya atau melakukan commit.
Import adalah langkah validasi Anda. Ini memasukkan definisi ke dalam proyek dan menyelesaikan $ref multi-file menjadi sumber daya terpadu. Jika file salah format, impor akan menampilkannya:
apidog import --project 123456 --format openapi --file ./openapi.json
Import menerima daftar panjang format di luar OpenAPI, termasuk Postman, HAR, Insomnia, WSDL, dan JSON Schema, yang berguna ketika sumber Anda bercampur.
Export adalah langkah bundle Anda, dengan bonus. Ini mengeluarkan file konsolidasi tunggal, dan Anda memilih versi OpenAPI saat keluar. Itu membuatnya menjadi bundle ditambah pemutakhiran spesifikasi opsional dalam satu perintah:
# Bundle dan tingkatkan ke OpenAPI 3.1 dalam satu langkah
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Atau mengeluarkan dokumen HTML mandiri
apidog export --project 123456 --format html --output ./docs.html
Untuk CI, Apidog menambahkan langkah yang tidak pernah dimiliki swagger-cli: menjalankan tes.
# Jalankan skenario tes di CI dengan beberapa format laporan
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Atau jalankan sepenuhnya offline dari file koleksi yang diekspor
apidog run ./collection.apidog-cli.json
CLI juga mengelola sumber daya proyek secara langsung, termasuk endpoint, schema, mock, environment, branch, test-suite, dan test-report. Untuk detail penyiapan dan setiap flag, lihat panduan lengkap Apidog CLI dan dokumen resmi Apidog CLI.
Sekarang batasan yang jujur, karena kesesuaian lebih penting daripada sensasi. CLI Apidog memvalidasi struktur saat impor, tetapi tidak memberi Anda linter panduan gaya yang dapat dikonfigurasi, berbasis kode, dengan seperangkat aturan khusus seperti yang dilakukan lint Redocly. Tidak ada perintah apidog lint, dan Anda tidak dapat membuat aturan kustom gaya Spectral melalui CLI. Juga tidak ada split atau join. Apidog mengutamakan GUI: desain, mocking, pembuatan tes visual, dan dokumen terutama dibuat di aplikasi desktop atau web, dengan CLI menangani impor, ekspor, menjalankan tes CI, dan manajemen sumber daya terhadap sebuah proyek. Dan Apidog adalah freemium, bukan sumber terbuka, jadi ini adalah model yang berbeda dari Redocly CLI dan Spectral.
Spectral: linting murni yang dapat disesuaikan di CI
Jika yang Anda inginkan dari swagger-cli adalah validasi yang ketat dan berpendirian dalam pipeline Anda, linter khusus adalah Spectral dari Stoplight. Ini adalah sumber terbuka dan dibangun untuk satu pekerjaan: menerapkan seperangkat aturan yang dapat disesuaikan pada dokumen OpenAPI (dan JSON/YAML lainnya).
Spectral bersinar ketika Anda ingin menegakkan gaya internal sebagai kode, dengan aturan Anda sendiri, di setiap pull request. Ia tidak menggabungkan, tidak membuat dokumen, dan tidak menguji endpoint; ia melakukan linting. Gabungkan dengan bundler dan Anda telah membangun kembali versi terfokus dari apa yang dilakukan swagger-cli, ditambah tata kelola yang nyata. Panduan kami untuk linting OpenAPI Spectral membahas penulisan aturan, dan memvalidasi OpenAPI di CI mencakup cara menghubungkannya ke pipeline.
Secara singkat: openapi-generator dan vacuum
Dua alat lagi muncul, jadi inilah versi singkat dan akuratnya. openapi-generator adalah generator kode dan klien; jika alasan Anda untuk bundling adalah untuk memberi makan generator, Anda mungkin tidak memerlukan langkah bundle terpisah sama sekali, karena ia mengonsumsi spesifikasi secara langsung. vacuum adalah linter OpenAPI yang cepat dan kompatibel dengan Spectral yang ditulis dalam Go, pilihan yang baik ketika kecepatan lint dalam monorepo besar menjadi penting. Keduanya bukan pengganti validate-plus-bundle umum dengan sendirinya, tetapi keduanya sesuai dengan kebutuhan spesifik.
Tabel perbandingan
Berikut adalah bagaimana opsi-opsi tersebut dibandingkan berdasarkan kemampuan yang cenderung diperhatikan oleh pengguna swagger-cli.
| Alat | Validasi | Gabungkan (Bundle) | Aturan Lint | Dokumen | Mock | Tes | Sumber terbuka | Terbaik untuk |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Ya | Ya | Tidak | Tidak | Tidak | Tidak | Ya (tidak digunakan lagi) | Tidak ada yang baru; tidak dikelola |
| Redocly CLI | Ya (lint) |
Ya | Ya (dapat dikonfigurasi) | Ya (Redoc HTML) | Tidak | Tidak | Ya | Pengganti terminal validate/bundle yang langsung pakai dengan tata kelola |
| Apidog | Ya (saat impor) | Ya (saat ekspor, dengan peningkatan OAS) | Hanya struktural, tanpa aturan kustom | Ya (aplikasi + ekspor) | Ya | Ya (jalankan CLI) | Tidak (freemium) | Satu alat untuk seluruh siklus hidup API |
| Spectral | Ya (berbasis lint) | Tidak | Ya (aturan kustom) | Tidak | Tidak | Tidak | Ya | Linting yang ketat dan dapat disesuaikan di CI |
| vacuum | Ya (berbasis lint) | Tidak | Ya (kompatibel dengan Spectral) | Tidak | Tidak | Tidak | Ya | Linting cepat pada spesifikasi besar |
Rekomendasi
Ini bukan situasi "semuanya hebat, pilih favorit Anda". Dua jalur jelas mencakup hampir semua orang.
Pilih Redocly CLI jika Anda menginginkan pengganti langsung. Ini adalah penerus resmi, sumber terbuka, dan migrasinya hampir mekanis: validate ke lint, bundle ke bundle, dengan pemetaan flag di atas. Jika alur kerja Anda benar-benar hanya "validasi dan bundle dari terminal", dan Anda ingin menambahkan aturan tata kelola nanti tanpa mengubah alat, Redocly adalah pilihan yang jelas. Ini membuat Anda mengutamakan kode dan berbasis terminal, persis di mana swagger-cli berada.
Pilih Apidog jika validasi dan bundle hanyalah permulaan. Kebanyakan tim tidak memvalidasi spesifikasi demi dirinya sendiri. Mereka memvalidasinya, kemudian seseorang membutuhkan mock untuk membangun, orang lain menulis tes, dan seseorang memiliki dokumennya. swagger-cli berhenti pada langkah pertama dan membuat Anda merakit sisanya dari Spectral, bundler, Postman, dan Newman. Apidog menghadirkan impor (validasi), ekspor (bundle ditambah peningkatan versi OAS), mock, tes, dan dokumen ke dalam satu ruang kerja, dengan CLI untuk bagian-bagian yang termasuk dalam CI. Anda berhenti mengawasi skrip statis yang sekarang tidak terpelihara dan membawa seluruh spesifikasi ke tempat di mana ia tetap berguna setelah digabungkan.
Ini adalah paradigma yang berbeda, bukan versi yang bersaing dari hal yang sama. Redocly CLI adalah spesialis ringan yang digerakkan oleh konfigurasi yang Anda jalankan murni dari terminal. Apidog adalah platform all-in-one yang memiliki CLI yang mumpuni. Pilihlah berdasarkan seberapa banyak siklus hidup yang Anda inginkan dalam satu alat, dan jujurlah tentang hal itu: jika Anda hanya ingin melakukan lint dan bundle di terminal, Redocly lebih ramping dan gratis.
Jika Anda ingin mencoba pendekatan siklus hidup, unduh Apidog dan impor spesifikasi yang ada; gratis untuk memulai, tidak memerlukan kartu kredit, dan Anda dapat melihat keluaran yang dibundle dan versi Anda dalam beberapa menit.
FAQ
Apakah swagger-cli masih dikelola?
Tidak. Repositori GitHub swagger-cli ditandai sebagai tidak digunakan lagi (deprecated) dan tidak lagi dikelola, dengan alasan kontribusi yang rendah dibandingkan dengan basis pengguna yang besar. Alat ini masih dapat diinstal dan dijalankan, tetapi tidak akan mendapatkan perbaikan atau pembaruan, jadi rencanakan migrasi.
Apa pengganti swagger-cli?
README proyek itu sendiri menunjuk ke Redocly CLI sebagai penerus. redocly lint menggantikan swagger-cli validate dan redocly bundle menggantikan swagger-cli bundle. Redocly bahkan menerbitkan panduan migrasi khusus. Jika Anda menginginkan lebih dari validasi dan bundle, Apidog mencakup impor, ekspor, mock, tes, dan dokumen di satu tempat.
Apakah Apidog gratis?
Apidog adalah freemium. Ada tingkatan gratis yang dapat Anda mulai tanpa kartu kredit, dengan paket berbayar untuk tim yang lebih besar dan kebutuhan lanjutan. Ini bukan sumber terbuka, yang merupakan perbedaan utama dari Redocly CLI dan Spectral jika lisensi terbuka adalah persyaratan bagi Anda.
Bisakah saya mempertahankan alur kerja swagger-cli saya persis seperti sebelumnya?
Yang paling mendekati adalah Redocly CLI. Untuk mencerminkan validate struktural sederhana swagger-cli, siapkan redocly.yaml hanya dengan aturan spec dan jalankan redocly lint. Untuk bundling, perintah dan flag hampir satu-ke-satu. Untuk melihat lebih dalam cakupan alat asli, lihat cara menggunakan swagger-cli dari terminal.