Cara Migrasi dari Swagger CLI ke Apidog CLI

Jika Anda masih menjalankan swagger-cli validate dan swagger-cli bundle di pipeline Anda, berarti Anda sedang mempertahankan skrip di sekitar alat yang tidak ada lagi yang memeliharanya. Repo GitHub swagger-cli sekarang menyatakannya secara langsung: paket tersebut tidak lagi dipelihara, README menyebutkan beban untuk mengikuti basis pengguna yang besar yang sedikit berkontribusi kembali, dan itu mengarahkan pengguna baru ke tempat lain.

Jadi ini adalah saat yang tepat untuk memutuskan di mana alur kerja spesifikasi Anda akan berada selanjutnya. Panduan ini adalah buku panduan migrasi, bukan tutorial penggunaan. Jika Anda belum siap untuk pindah dan hanya ingin terus menggunakan alat lama, panduan Swagger CLI mencakup validate dan bundle secara rinci. Artikel ini adalah tentang beralih, khususnya cara memigrasi Swagger CLI ke Apidog CLI tanpa merusak CI Anda.

Unduh Apidog jika Anda ingin mengikuti dengan perintah nyata. Gratis untuk memulai, tidak memerlukan kartu kredit.

tombol

Mengapa Bermigrasi Sekarang

Jawaban jujur pertama: swagger-cli telah usang dan tidak dipelihara selama beberapa waktu. Itu masih berjalan. Banyak pipeline yang memanggilnya hari ini. Tetapi alat yang tidak akan mendapatkan perbaikan bug atau pembaruan spesifikasi adalah utang teknis yang ada dalam pembangunan Anda, dan para pemelihara sendiri merekomendasikan untuk beralih.

Mereka menunjuk satu penerus secara khusus. Redocly CLI adalah pengganti langsung terdekat jika yang Anda inginkan hanyalah validasi ditambah bundling di terminal. Ini adalah sumber terbuka, code-first, dan terminal-native. Perintah lint-nya melakukan validasi struktural, dan redocly bundle mengikuti pointer $ref persis seperti yang dilakukan swagger-cli bundle. Jika satu-satunya tujuan Anda adalah pertukaran 1:1 yang menjaga spesifikasi sebagai file datar di repo Anda, Redocly adalah pilihan alami, dan Redocly menerbitkan panduan migrasinya sendiri dengan pemetaan perintah. Tidak ada salahnya mengambil jalur itu.

Apidog memiliki tujuan yang berbeda. Migrasi ke Apidog CLI saat Anda ingin spesifikasi melakukan lebih dari sekadar berada dalam file. Alih-alih memvalidasi dan membundel dokumen statis, Anda membawa seluruh definisi ke dalam ruang kerja yang aktif, lalu memvalidasinya saat diimpor, mengekspor file yang terkonsolidasi saat Anda membutuhkannya, dan secara opsional melakukan mock API, menjalankan skenario pengujian terhadapnya, dan menerbitkan dokumen dari sumber yang sama. swagger-cli hanya melakukan dua hal. Apidog mencakup sisa siklus hidup.

Pilih berdasarkan kesesuaian, bukan karena promosi. Jika Anda menginginkan linter dan bundler ringan, berbasis konfigurasi yang Anda jalankan murni dari terminal, Redocly adalah pemenangnya. Jika Anda lebih suka memiliki satu platform untuk desain, mocking, pengujian, dan dokumentasi daripada menyatukan beberapa alat, Apidog adalah pemenangnya.

Apa yang dilakukan swagger-cli vs apa yang dilakukan Apidog CLI

swagger-cli hanya memiliki dua perintah:

swagger-cli validate <file> memeriksa dokumen Swagger 2.0 atau OpenAPI 3.0 terhadap skema dan memverifikasi pointer $ref-nya diselesaikan.
swagger-cli bundle <file> mengikuti pointer $ref tersebut dan menggabungkan definisi multi-file menjadi satu file, dengan opsi untuk jalur output (-o), tipe (-t json|yaml), dereferensi penuh (-r), dan indentasi (-f).

Itu adalah keseluruhan alatnya. Itu tidak melakukan linting dengan aturan gaya, menghasilkan dokumen, menjalankan pengujian, atau mocking apa pun.

Apidog CLI memetakan dua pekerjaan tersebut ke dua perintahnya, lalu terus berlanjut:

apidog import menyerap definisi ke dalam proyek Apidog dan memvalidasinya saat masuk. Spesifikasi multi-file akan memiliki pointer $ref-nya diselesaikan menjadi sumber daya terpadu secara otomatis. Ini adalah langkah validasi Anda, ditambah penyerapan.
apidog export mengeluarkan satu file terkonsolidasi dari proyek, dan memungkinkan Anda memilih versi OpenAPI saat keluar. Ini adalah langkah bundling Anda, ditambah peningkatan versi opsional dan kemampuan untuk mengeluarkan dokumen HTML atau Markdown.
apidog run mengeksekusi skenario dan suite pengujian, dengan JUnit dan reporter lain untuk CI. swagger-cli tidak memiliki padanan.
Perintah sumber daya (endpoint, schema, mock, environment, branch, dan lainnya) mengelola proyek dari terminal setelah spesifikasi masuk.

Satu poin penting agar pemetaan tetap jujur: Apidog memvalidasi struktur saat diimpor, tetapi ini bukan linter panduan gaya yang dapat dikonfigurasi. Tidak ada apidog lint dan tidak ada aturan kustom. Jika Anda mengandalkan linting yang bersifat opinionated, bagian itu tidak akan terbawa, dan bagian Apa yang Anda Dapatkan mencakup cara menanganinya.

Instal dan Masuk

Apidog CLI dikirim sebagai paket npm. Instal secara global:

npm install -g apidog-cli@latest

Kemudian otentikasi dengan token akses:

apidog login --with-token <TOKEN>

Anda mendapatkan token dari aplikasi atau web Apidog: klik avatar Anda, buka Pengaturan Akun, lalu Token Akses API, dan buat satu. CLI menyimpannya di ~/.apidog/config.toml. Perlakukan seperti rahasia lainnya. Jangan mencetaknya di log atau mengcommitnya ke repo Anda.

Jika Anda ingin setiap flag dan tur yang lebih mendalam, panduan lengkap Apidog CLI dan dokumen resmi Apidog CLI mencakup seluruh permukaannya. Untuk migrasi ini, instalasi ditambah login adalah semua yang Anda butuhkan untuk memulai.

Tabel Pemetaan Perintah

Berikut adalah terjemahan langsung dari swagger-cli ke Apidog CLI. Satu perbedaan struktural: Apidog bekerja melawan sebuah proyek, jadi sebagian besar alur adalah impor-lalu-ekspor daripada satu perintah pada file yang lepas.

Perintah swagger-cli	Padanan Apidog CLI	Apa yang berubah
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	Memvalidasi spesifikasi saat diimpor; spesifikasi yang tidak valid menyebabkan perintah gagal
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` lalu `apidog export --project <id> --format openapi --output ./out.json`	Bundling menjadi ekspor dari proyek; `$refs` sudah diselesaikan saat diimpor
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	Format output mengikuti file yang Anda tulis
(tidak ada padanan)	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	Meng-upgrade spesifikasi 2.0 atau 3.0 ke 3.1 saat ekspor
(tidak ada padanan)	`apidog export --project <id> --format html --output ./docs.html`	Mengeluarkan dokumen HTML mandiri
(tidak ada padanan)	`apidog export --project <id> --format markdown --output ./docs.md`	Mengeluarkan dokumen Markdown
(tidak ada padanan)	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	Menjalankan pengujian API di CI

Dua sel yang paling penting untuk migrasi adalah dua baris pertama. Semua yang di bawahnya adalah kemampuan yang tidak pernah dimiliki swagger-cli. Flag --oas-version adalah peningkatan yang paling jelas: swagger-cli dapat membundel file Swagger 2.0, tetapi tidak dapat mengubahnya menjadi OpenAPI 3.1. Apidog dapat melakukannya, saat ekspor, yang berguna ketika Anda memodernisasi kontrak lama. Jika tujuan Anda adalah output dokumen secara spesifik, mengekspor OpenAPI ke Markdown menjelaskan format tersebut lebih mendalam.

Migrasi Langkah demi Langkah

Berikut adalah jalur lengkap dari pengaturan swagger-cli ke alur kerja Apidog yang berfungsi.

1. Dapatkan ID proyek Anda. Buat atau buka proyek di aplikasi Apidog. ID proyek muncul di pengaturan proyek dan di URL. Anda akan meneruskannya ke setiap perintah CLI melalui --project.

2. Impor spesifikasi utama. Arahkan Apidog ke file entri definisi Anda. Spesifikasi multi-file dengan pointer $ref diselesaikan secara otomatis, jadi Anda mengimpor yang utama dan Apidog menarik sisanya:

apidog import --project 123456 --format openapi --file ./openapi.yaml

Jika spesifikasi salah format atau $ref menggantung, impor akan gagal. Kegagalan itu adalah gerbang validasi Anda, pekerjaan yang sama yang dulu dilakukan swagger-cli validate, kini digabungkan ke dalam penyerapan.

3. Verifikasi di aplikasi. Buka proyek dan konfirmasikan endpoint, skema, dan parameter Anda berhasil masuk. Pemeriksaan visual ini tidak memiliki padanan swagger-cli, dan patut dilakukan sekali selama migrasi untuk mengonfirmasi impor berjalan sesuai harapan Anda.

4. Ekspor file yang terkonsolidasi. Ketika Anda membutuhkan satu file datar (untuk alat hilir, generator klien, atau artefak), ekspor. Pilih versi OpenAPI yang Anda inginkan:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Itu menggantikan swagger-cli bundle. Pointer $ref sudah diselesaikan saat diimpor, jadi ekspor adalah output file tunggal yang terkonsolidasi.

5. Hubungkan ke CI. Ganti langkah swagger-cli lama Anda dengan impor (validasi saat penyerapan) dan ekspor (bundle), dan tambahkan uji coba jika Anda memiliki skenario. Bagian berikutnya memiliki contoh GitHub Actions lengkap.

Contoh CI dengan GitHub Actions

Alur kerja ini menginstal CLI, masuk dengan token dari rahasia repo, mengimpor spesifikasi untuk memvalidasinya, mengekspor artefak yang terkonsolidasi, lalu menjalankan skenario pengujian dengan reporter JUnit sehingga pengujian yang gagal akan menyebabkan pemeriksaan gagal dan mengunci PR.

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Simpan token sebagai APIDOG_ACCESS_TOKEN di rahasia repo Anda agar tidak pernah muncul di log. Reporter -r "cli,junit" menulis file XML JUnit yang dapat ditampilkan CI Anda sebagai laporan pengujian, dan skenario yang gagal mengembalikan kode keluar bukan nol yang memblokir penggabungan. Untuk pola pipeline yang lebih mendalam, lihat panduan CI/CD Apidog CLI, dan untuk pengaturan khusus runner, panduan Apidog CLI dengan GitHub Actions.

Apa yang Anda Dapatkan di Luar Validasi dan Bundling

Di sinilah migrasi membuahkan hasil, dan di sinilah kejujuran paling penting.

Server Mock. Setelah spesifikasi Anda ada dalam proyek, Apidog dapat menyajikan respons mock darinya. Anda dapat mengembangkan frontend terhadap API sebelum backend ada. swagger-cli tidak pernah menyentuh perilaku runtime.

Skenario pengujian otomatis. apidog run mengeksekusi permintaan nyata terhadap API yang sedang berjalan dan menegaskan responsnya. Anda membangun skenario secara visual di aplikasi, lalu menjalankannya secara headless di CI. Itu menutup celah yang ditinggalkan swagger-cli lebar-lebar: spesifikasi yang valid memberi tahu Anda bahwa kontraknya terbentuk dengan baik, bukan bahwa implementasinya cocok dengannya.

Dokumen yang Dihosting dan Diekspor. apidog export --format html atau --format markdown menghasilkan dokumen langsung dari sumber yang sama. Tidak ada langkah pembangunan dokumen terpisah untuk dipelihara.

Sekarang, batas yang jujur. Apidog CLI tidak memiliki linter panduan gaya code-first yang dapat dikonfigurasi dengan kumpulan aturan kustom. Ini memvalidasi struktur saat diimpor, tetapi Anda tidak dapat membuat aturan gaya Spectral atau Redocly melalui CLI, dan tidak ada perintah apidog lint. Jika pengaturan lama Anda sangat mengandalkan linting (penamaan yang konsisten, deskripsi yang wajib, contoh pada setiap respons), pertahankan linter khusus. Pasangkan Apidog dengan Spectral atau Redocly untuk itu, dan jalankan sebagai langkah CI terpisah. Panduan pengaturan linter OpenAPI mencakup cara menyambungkannya. Menggunakan keduanya bukanlah kontradiksi: linting dengan alat spesialis, lalu kelola siklus hidup di Apidog.

tombol