Redocly CLI adalah alat yang bagus. Jika Anda pernah menggunakannya untuk melintasi file OpenAPI, menggabungkan spesifikasi multi-file menjadi satu, atau membangun dokumen Redoc dari terminal, Anda sudah mengetahuinya. Jadi, mengapa mencari alternatif Redocly CLI sama sekali?
Biasanya ini bergantung pada bentuknya. Redocly CLI adalah spesialis yang fokus pada kode-pertama: lint, bundle, split, join, build docs. Itu sangat tepat untuk beberapa tim dan tidak cukup untuk yang lain. Jika Anda menginginkan satu alat yang juga merancang, mengejek (mock), dan menguji API Anda, CLI tidak mencoba menjadi alat itu, dan memang seharusnya tidak demikian.
Artikel ini tentang **Redocly CLI** (paket sumber terbuka @redocly/cli), bukan produk dokumen Redocly yang di-hosting. Jika Anda membandingkan platform dokumen yang di-hosting atau Redoc itu sendiri, bacalah rangkuman alternatif Redocly kami untuk dokumentasi API sebagai gantinya. Postingan ini untuk orang-orang yang mengetik redocly lint dan redocly bundle dan ingin tahu apa lagi yang sesuai dengan alur kerja mereka.
Apa yang sebenarnya dilakukan Redocly CLI dengan baik
Redocly CLI adalah sumber terbuka dan berbasis terminal. Anda menginstalnya sekali dan mendapatkan serangkaian perintah yang ringkas yang menjalankan tugasnya dengan bersih. Dokumen Redocly CLI mencakup semuanya, tetapi berikut adalah versi singkatnya.
Linting adalah kekuatan utamanya. redocly lint memvalidasi deskripsi OpenAPI, AsyncAPI, Arazzo, atau Open-RPC Anda, kemudian menjalankan aturan panduan gaya di atasnya. Anda mengonfigurasi semuanya melalui file redocly.yaml: pilih kumpulan aturan bawaan (minimal, recommended, recommended-strict, atau spec) atau buat aturan kustom Anda sendiri. Tata kelola berbasis konfigurasi itu sulit ditandingi jika Anda ingin desain API yang konsisten ditegakkan di CI di banyak tim.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Bundle, split, dan join menangani perpipaan spesifikasi. redocly bundle mengikuti penunjuk $ref dan menghasilkan satu file konsolidasi. redocly split melakukan kebalikannya, memecah satu deskripsi menjadi tata letak multi-file. redocly join (eksperimental) menggabungkan beberapa file OpenAPI menjadi satu.
redocly bundle openapi.yaml --output dist/openapi.json
Dokumen berasal dari build-docs. Ini menghasilkan halaman HTML Redoc mandiri, dan preview-docs memberi Anda pratinjau lokal secara langsung.
redocly build-docs openapi.yaml -o docs.html
Jadi, jika kebutuhan Anda adalah “validasi terhadap panduan gaya, bundel spesifikasi, dan kirim dokumen Redoc, semuanya dari terminal,” Redocly CLI adalah pilihan default yang kuat. Banyak tim harus tetap menggunakannya. Alasan untuk mencari alternatif adalah tentang cakupan, bukan kualitas.
Mengapa orang mencari alternatif
Beberapa pola muncul berulang kali:
- Anda menginginkan platform lengkap, bukan hanya lint ditambah docs. Redocly CLI tidak menjalankan tes API dan tidak meng-hosting server tiruan (mock server). Jika Anda juga membutuhkan desain, mocking, dan test runner, Anda sedang merakit toolchain di sekitarnya.
- Anda menginginkan GUI di samping CLI. Redocly adalah code-first berdasarkan desain. Jika tim Anda mencakup orang-orang yang lebih suka bekerja secara visual, tata kelola berbasis terminal saja akan sulit dijual.
- Anda menginginkan test runner bawaan untuk CI. Linting menangkap masalah spesifikasi. Ini tidak memberi tahu Anda apakah API yang berjalan berfungsi dengan baik. Itu adalah alat yang terpisah.
- Anda tidak ingin menggabungkan lima alat. Spectral untuk lint, Redocly untuk bundle dan docs, Postman atau Newman untuk tes, alat lain untuk mock. Itu berfungsi, tetapi ada banyak bagian yang bergerak untuk dipelihara.
Masing-masing poin tersebut mengarah pada alternatif yang berbeda. Mari kita cocokkan.
Daftar singkat, berdasarkan apa yang sebenarnya Anda inginkan
Apidog, jika Anda menginginkan satu platform untuk seluruh siklus hidup API
Apidog adalah platform API lengkap: desain, mocking, pengujian, dan dokumentasi di satu tempat, dengan CLI untuk import, export, dan eksekusi tes CI. Ini adalah pilihan yang tepat jika Anda lebih suka memiliki satu alat untuk seluruh siklus hidup daripada menggabungkan linter, bundler, test runner, dan mock server.
Ini bagian jujurnya. Apidog tidak memiliki linter panduan gaya berbasis kode-pertama yang dapat dikonfigurasi dengan kumpulan aturan kustom seperti lint Redocly. Tidak ada perintah apidog lint dan tidak ada cara untuk membuat aturan kustom gaya Spectral atau Redocly melalui CLI. Apidog memvalidasi struktur saat Anda mengimpor spesifikasi, tetapi jika tata kelola desain yang ketat dan dapat disesuaikan adalah satu-satunya hal yang Anda pedulikan, Apidog tidak akan menggantikan redocly lint sendiri. Pasangkan dengan Spectral untuk tugas itu. Kita akan kembali ke ini.
Apa yang Apidog berikan kepada Anda yang tidak dimiliki Redocly CLI: perancang visual, mock server bawaan, pembangun tes visual, dan test runner CI. CLI menangani bagian-bagian yang berada di terminal.
# Install dan otentikasi (token dari aplikasi: avatar > Account Settings > API Access Token)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Impor spesifikasi ke dalam proyek (memvalidasi + menyelesaikan $ref multi-file)
apidog import --project 123456 --format openapi --file ./openapi.json
# Ekspor satu file konsolidasi, dan pilih versi OpenAPI Anda
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Jalankan skenario tes di CI dengan beberapa format laporan
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import melakukan tugas validasi saat masuk, dan apidog export melakukan tugas bundling saat keluar (ia mengeluarkan satu file dan dapat memperbarui versi OAS). Daftar perintah lengkap terdapat di dokumen Apidog CLI, dan panduan Apidog CLI lengkap kami membahas setiap flag. Terbaik untuk: tim yang menginginkan desain, mock, pengujian, dan dokumentasi di bawah satu atap.
Spectral, jika yang Anda inginkan dari Redocly hanyalah linter
Jika satu-satunya hal yang Anda gunakan adalah redocly lint, Anda tidak perlu mengganti platform. Spectral dari Stoplight adalah linter berbasis aturan sumber terbuka yang paling tumpang tindih secara langsung dengan linting Redocly. Anda menulis aturan dalam YAML, menjalankannya terhadap dokumen OpenAPI atau AsyncAPI apa pun, dan mengintegrasikannya ke dalam CI.
Linter Spectral dan Redocly adalah sepupu dekat. Keduanya digerakkan oleh konfigurasi, keduanya menyediakan kumpulan aturan, keduanya memungkinkan Anda membuat aturan kustom. Pilihan di antara keduanya seringkali bergantung pada kesesuaian ekosistem dan format kumpulan aturan yang sudah diketahui tim Anda. Pembahasan mendalam kami tentang linting Spectral OpenAPI mencakup pembuatan aturan, dan panduan linting API yang lebih luas membandingkan lanskap linting jika Anda ingin gambaran lengkapnya. Terbaik untuk: tim yang kebutuhan sebenarnya adalah linting spesifikasi yang murni dan dapat disesuaikan.
Scalar atau Bump.sh, jika Anda kebanyakan menginginkan dokumen
Jika bagian dari Redocly CLI yang Anda pedulikan adalah build-docs, alternatifnya adalah alat dokumentasi, bukan platform. Scalar dan Bump.sh keduanya mengubah deskripsi OpenAPI menjadi dokumen referensi yang di-hosting dan dapat dijelajahi, masing-masing dengan tampilan dan fitur sendiri. Mereka berfokus pada pengalaman dokumen daripada linting atau pengujian. Terbaik untuk: tim yang tujuan utamanya adalah dokumen referensi API yang terlihat bagus dan mudah dipelihara.
swagger-cli, yang sebenarnya bukan pilihan lagi
Anda masih akan melihat swagger-cli disebutkan di panduan lama, jadi penting untuk menjelaskan: swagger-cli sudah usang. Repositori GitHub swagger-cli menyatakan bahwa itu tidak lagi dipelihara dan mengarahkan pengguna ke Redocly CLI sebagai penerusnya.
Ia hanya memiliki dua perintah, swagger-cli validate dan swagger-cli bundle. Ia tidak pernah melakukan linting dengan aturan gaya, tidak pernah menghasilkan dokumen, tidak pernah menjalankan tes, dan tidak pernah melakukan mocking apa pun. Jika Anda menggunakannya hari ini, langkahnya adalah beralih darinya, bukan kepadanya. Panduan kami tentang cara menggunakan swagger-cli mencakup apa yang dilakukannya, dan Redocly bahkan menerbitkan panduan migrasi dari swagger-cli dengan pemetaan flag yang tepat. Kami akan menyertakan pemetaan itu di bawah ini untuk kelengkapan.
Tabel Perbandingan
Berikut adalah bagaimana opsi-opsi ini sesuai dengan tugas-tugas yang ditangani Redocly CLI. “Lint aturan kustom” berarti linter panduan gaya berbasis kode-pertama yang dapat dikonfigurasi dengan kumpulan aturan kustom.
| Alat | Lint aturan kustom | Bundle | Dokumen | Mock | Uji | GUI | Sumber terbuka | Terbaik untuk |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Ya | Ya | Ya (Redoc) | Tidak | Tidak | Tidak | Ya | Lint, bundle, dan tata kelola dokumen berbasis kode-pertama dari terminal |
| Apidog | Tidak | Melalui ekspor | Ya | Ya | Ya (runner CI) | Ya | Tidak (freemium) | Satu platform untuk desain, mock, pengujian, dan dokumen |
| Spectral | Ya | Tidak | Tidak | Tidak | Tidak | Tidak | Ya | Linting OpenAPI/AsyncAPI murni yang dapat disesuaikan |
| Scalar / Bump.sh | Tidak | Tidak | Ya | Tidak | Tidak | Ya | Bervariasi | Dokumen referensi API yang di-hosting |
| swagger-cli | Tidak | Ya | Tidak | Tidak | Tidak | Tidak | Ya (usang) | Tidak ada yang baru, tidak lagi dipelihara |
Catatan pada tabel: “Melalui ekspor” Apidog berarti apidog export mengeluarkan satu file konsolidasi, yang mencakup alasan praktis Anda akan menjalankan redocly bundle, tetapi itu bukan perintah bundle yang sama persis. Dan Apidog adalah freemium, bukan sumber terbuka, sementara Redocly CLI dan Spectral keduanya sumber terbuka. Sebut saja kompromi-kompromi itu apa adanya.
Pemetaan flag bundle swagger-cli ke Redocly CLI
Jika Anda menggunakan swagger-cli yang sudah usang dan Redocly adalah tujuan Anda untuk bundling, flag-flagnya cocok dengan rapi:
| swagger-cli | Redocly CLI | Arti |
|---|---|---|
-o, --outfile <file> |
--output (atau -o) |
Tulis ke file alih-alih stdout |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Tipe file output |
-r, --dereference |
-d, --dereferenced |
Sematkan sepenuhnya semua $refs |
Jadi swagger-cli bundle -o output.json menjadi redocly bundle --output output.json.
Rekomendasi yang jelas
Tidak ada satu pemenang tunggal, karena jawaban yang tepat bergantung pada pekerjaan Redocly CLI mana yang ingin Anda gantikan.
Pertahankan Redocly CLI jika tata kelolanya persis seperti yang Anda butuhkan. Linter, bundler, dan pembangun dokumen Redoc yang ringan, sumber terbuka, digerakkan oleh konfigurasi, yang Anda jalankan sepenuhnya dari terminal adalah pengaturan yang benar-benar baik. Tidak ada alasan di sini untuk meninggalkan alat yang cocok.
Pilih Apidog jika Anda lelah merakit toolchain dan menginginkan desain, mocking, pengujian, dan dokumentasi dalam satu platform dengan CLI untuk bagian-bagian berbentuk terminal. Anda berhenti memelihara alat terpisah untuk setiap tahap dan mendapatkan GUI untuk orang-orang di tim Anda yang menginginkannya. Hanya saja, pahamilah bahwa Anda akan memasangkannya dengan Spectral jika Anda juga membutuhkan linting aturan kustom. Panduan Apidog CLI di CI/CD menunjukkan bagaimana test runner masuk ke dalam pipeline, dan Apidog CLI vs Newman membandingkannya dengan runner yang sudah banyak digunakan tim. Anda dapat mengunduh Apidog dan mencobanya secara gratis, tanpa kartu kredit.
Pilih Spectral jika linting adalah tujuan utamanya. Jangan beralih platform hanya untuk mengganti satu perintah.
Gambaran jujurnya: Redocly adalah spesialis CLI berbasis kode-pertama, dan Apidog adalah platform visual lengkap. Keduanya adalah paradigma yang berbeda, bukan pengganti langsung. Pilihlah berdasarkan kesesuaian.
FAQ
Apakah Apidog pengganti langsung untuk Redocly CLI? Tidak, dan lebih baik jujur tentang itu. Apidog mencakup lebih banyak siklus hidup (desain, mock, uji, dokumen) tetapi tidak memiliki linter kumpulan aturan kustom seperti redocly lint. Jika tata kelola spesifikasi yang ketat dan dapat dikonfigurasi adalah tugas utama Anda, pertahankan linter Redocly atau gunakan Spectral. Apidog unggul ketika Anda menginginkan satu alat untuk seluruh siklus hidup API daripada beberapa alat.
Apakah Apidog CLI memiliki perintah lint? Tidak. Apidog memvalidasi struktur saat Anda mengimpor spesifikasi dengan apidog import, tetapi tidak ada apidog lint dan tidak ada cara untuk membuat aturan kustom gaya Spectral atau Redocly melalui CLI. Untuk itu, pasangkan Apidog dengan Spectral.
Bisakah saya menggabungkan (bundle) file OpenAPI tanpa Redocly CLI? Ya. apidog export --project <id> --format openapi --output ./openapi.json mengeluarkan satu file konsolidasi dan dapat menargetkan versi OpenAPI tertentu dengan --oas-version. Ini bukan perintah bundle secara harfiah, tetapi mencakup kebutuhan praktis yang sama. Jika Anda hanya ingin bundling dan tidak ada yang lain, redocly bundle masih merupakan pilihan yang bagus dan fokus.
Haruskah saya menggunakan swagger-cli di tahun 2026? Tidak. swagger-cli sudah usang dan tidak dipelihara, dan repositori resminya sendiri menunjuk ke Redocly CLI sebagai penerusnya. Ia hanya pernah memvalidasi dan menggabungkan. Gunakan Redocly CLI untuk tugas itu, atau beralih ke platform seperti Apidog jika Anda juga menginginkan sisa siklus hidupnya.
Apa perbedaan antara ini dan perbandingan platform dokumen Redocly? Postingan ini tentang alat sumber terbuka @redocly/cli: lint, bundle, split, join, dan build-docs. Jika Anda membandingkan produk dokumen Redocly yang di-hosting atau Redoc sebagai perender dokumentasi, bacalah alternatif Redocly untuk dokumentasi API sebagai gantinya. Keduanya mencakup produk yang berbeda yang kebetulan berbagi nama. Untuk spesifikasi itu sendiri, Spesifikasi OpenAPI adalah sumber kebenaran, dan Redocly CLI di npm adalah tempat Anda akan menemukan detail instalasi saat ini.