DEV Community

Cover image for Alat CLI Ringan Terbaik untuk Kolaborasi API
Walse
Walse

Posted on • Originally published at apidog.com

Alat CLI Ringan Terbaik untuk Kolaborasi API

Kolaborasi API dulu sering berarti membuka aplikasi berat, menunggu sinkronisasi, lalu mencari panel untuk mengetahui perubahan rekan setim. Jika API Anda didefinisikan dalam file OpenAPI, sebagian besar kolaborasi sebenarnya adalah pekerjaan berbasis teks: membuat versi spesifikasi, meninjau perbedaan (diff), dan menggabungkan perubahan. Semua itu dapat dilakukan dari terminal.

Coba Apidog hari ini

Panduan ini membahas alat CLI ringan untuk tiga pekerjaan tersebut. Setiap alat dapat dipasang dan dijalankan cepat, serta cocok diintegrasikan dengan Git atau CI. Untuk gambaran alur kerja tim yang lebih luas, lihat rangkuman alat kolaborasi API. Artikel ini berfokus pada alur kerja berbasis terminal.

Kerangkanya sederhana:

  1. Membuat versi spesifikasi — mengetahui versi API yang sedang digunakan dan riwayat perubahannya.
  2. Meninjau perubahan — melihat apa yang berubah dan apakah perubahan tersebut merusak klien.
  3. Menggabungkan perubahan — memasukkan perubahan yang sudah ditinjau ke sumber kebenaran bersama.

Semua alat di bawah bekerja dengan OpenAPI, standar resmi yang menjadi format bersama untuk spesifikasi API.

Apa yang membuat alat CLI ringan untuk kolaborasi API?

Sebuah alat CLI dapat disebut ringan jika memenuhi sebagian besar kriteria berikut:

  • Instalasi kecil — biner tunggal, pemanggilan npx, atau satu npm install -g.
  • Startup cepat — dapat dijalankan dari skrip, hook Git, atau pipeline CI tanpa proses latar belakang.
  • Konfigurasi minimal — cukup arahkan ke openapi.yaml atau file spesifikasi Anda.
  • Berorientasi terminal — output mudah dibaca di shell atau dikirim ke log CI.
  • Fokus pada satu pekerjaan — misalnya membandingkan diff, menerbitkan dokumentasi, atau mengelola merge.

Mulailah dari Git sebagai fondasi. Lalu tambahkan alat semantic diff, linting, dokumentasi, atau alur merge sesuai kebutuhan tim.

Git + file spesifikasi: fondasi kolaborasi

Cara paling ringan untuk berkolaborasi adalah menyimpan file OpenAPI di repositori yang sama dengan kode aplikasi. Git sudah menyediakan riwayat, branch, pull request, komentar per baris, dan merge.

# Lacak spesifikasi seperti file kode lainnya
git add openapi.yaml
git commit -m "Tambahkan parameter paginasi ke GET /orders"

# Tinjau perubahan spesifikasi terhadap branch utama
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Gunakan pendekatan ini sebagai baseline:

repo/
├── src/
├── tests/
└── openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dengan struktur tersebut, setiap perubahan endpoint dapat ditinjau bersama perubahan implementasinya. Ini adalah inti dari kolaborasi API Git-native.

Terbaik untuk: riwayat dan tinjauan tanpa memasang alat baru.

Batas jujur: diff Git pada YAML bisa berisik. Perubahan indentasi, urutan key, atau format dapat terlihat sebagai perubahan besar walaupun kontrak API tidak berubah. Untuk itu, tambahkan semantic diff seperti oasdiff atau Optic.

oasdiff: blokir perubahan breaking di CI

oasdiff adalah biner Go yang membandingkan dua spesifikasi OpenAPI dan mendeteksi perubahan yang bersifat breaking. Karena menggunakan kode keluar (exit code), alat ini cocok dijadikan gerbang merge di CI.

# Instal di macOS
brew install oasdiff

# Bandingkan spesifikasi dasar dan perubahan dari PR
oasdiff breaking main-spec.yaml pr-spec.yaml

# exit 0 = tidak ada perubahan breaking
# exit 1 = ditemukan perubahan breaking
Enter fullscreen mode Exit fullscreen mode

Untuk melihat seluruh ringkasan perubahan, bukan hanya perubahan breaking:

oasdiff changelog main-spec.yaml pr-spec.yaml
Enter fullscreen mode Exit fullscreen mode

Contoh penggunaan dalam GitHub Actions:

- name: Check OpenAPI breaking changes
  run: oasdiff breaking main-spec.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Jika perintah mengembalikan kode keluar 1, pipeline gagal sebelum perubahan digabungkan.

Terbaik untuk: menjadikan deteksi perubahan breaking sebagai gerbang merge.

Batas jujur: oasdiff membandingkan dan melaporkan perubahan. Ia tidak mengelola branch, PR, atau publikasi dokumentasi.

Optic: tinjau perubahan API dalam konteks Git

Optic adalah CLI berbasis npm untuk membandingkan, melinting, dan meninjau perubahan OpenAPI dengan alur kerja Git. Optic memahami struktur seperti $ref, oneOf, dan allOf, yang sering membuat diff biasa sulit dibaca.

# Instal
npm install -g @useoptic/optic

# Bandingkan openapi.yaml saat ini dengan versi pada main
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

Gunakan Optic ketika Anda ingin hasil review yang lebih terstruktur daripada diff YAML mentah. Jalankan perintahnya sebelum membuka PR atau sebagai langkah CI.

# Contoh hook atau skrip CI
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: tinjauan perubahan OpenAPI yang terstruktur dalam pull request.

Batas jujur: karena berbasis Node, Optic lebih berat daripada biner Go tunggal. Anda juga perlu mengadopsi konfigurasi dan aturan pemeriksaannya untuk hasil maksimal.

Bump.sh CLI: terbitkan dokumentasi bersama

CLI Bump.sh digunakan untuk menerbitkan dan membandingkan dokumentasi API dari terminal. Model kolaborasinya berpusat pada satu dokumentasi bersama yang selalu diperbarui dari spesifikasi.

# Instal
npm install -g bump-cli

# Terbitkan spesifikasi baru ke dokumentasi bersama
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# Bandingkan file lokal dengan versi dokumentasi yang diterbitkan
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

Gunakan bump diff untuk menghasilkan daftar perubahan yang dapat dimasukkan ke komentar PR. Gunakan bump deploy setelah perubahan disetujui dan digabungkan.

Terbaik untuk: menjaga dokumentasi API bersama tetap sinkron dengan spesifikasi.

Batas jujur: dokumentasi yang di-host dan alur deploy adalah bagian dari produk berbayar Bump.sh. CLI berperan sebagai klien untuk platform tersebut. Paket ini membutuhkan Node 20+, sedangkan preview dan diff dapat digunakan tanpa token.

Redocly CLI: lint, bundle, lalu push spesifikasi

Redocly CLI adalah toolkit OpenAPI untuk linting, bundling, dan mendorong spesifikasi ke registri Redocly, yang sekarang disebut Reunite.

Langkah praktis untuk spesifikasi multi-file:

# Lint spesifikasi
npx @redocly/cli lint openapi.yaml

# Bundle $ref menjadi satu file artefak
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Setelah valid, dorong spesifikasi ke registri bersama:

# Membutuhkan API key dan akses ke organisasi/proyek
npx @redocly/cli push openapi.yaml \
  --organization "Acme" \
  --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

Bundling penting jika spesifikasi Anda dipisah ke banyak file menggunakan $ref. Rekan tim dan pipeline kemudian dapat mengonsumsi satu artefak, misalnya dist/openapi.yaml.

Terbaik untuk: menerapkan aturan gaya internal, membundel spesifikasi, dan menyimpan sumber kebenaran di registri bersama.

Batas jujur: lint dan bundle gratis serta berjalan lokal. Perintah push dan registri merupakan bagian dari platform hosting Redocly. Untuk alur kerja pengeditan spesifikasi, lihat panduan pengeditan spesifikasi API kolaboratif.

GitHub CLI (gh): kelola PR dari shell

Jika tim Anda menggunakan GitHub, GitHub CLI memungkinkan Anda membuka PR, meminta reviewer, dan memeriksa status tanpa meninggalkan terminal.

# Buat PR untuk perubahan spesifikasi
gh pr create \
  --title "Tambahkan paginasi /orders" \
  --body "Menambahkan parameter page + limit"

# Setujui PR
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

Pasangkan gh dengan oasdiff atau Optic agar review PR juga mencakup validasi kontrak API.

Contoh alur kerja:

# 1. Validasi semantic diff
oasdiff breaking main-spec.yaml openapi.yaml

# 2. Commit perubahan
git add openapi.yaml
git commit -m "Tambahkan paginasi /orders"

# 3. Buat PR
gh pr create --title "Tambahkan paginasi /orders"
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: menjalankan alur review dan merge GitHub dari shell.

Batas jujur: gh mengelola PR, bukan semantik API. Gunakan bersama oasdiff atau Optic untuk mendeteksi perubahan breaking.

Apidog CLI: branch, review, dan merge dalam satu CLI

Apidog CLI adalah pengecualian dibanding alat lain di daftar ini. Ini bukan biner untuk satu fungsi saja, melainkan CLI sumber daya proyek yang terhubung ke platform Apidog. Untuk kolaborasi, perintah yang penting adalah:

  • branch
  • merge-request
  • git-connection

Instal dan autentikasi terlebih dahulu:

npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

Buat branch terisolasi untuk perubahan API:

# Branch sprint untuk fitur atau rilis terfokus
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

Flag --type memilih model branch:

  • sprint untuk fitur atau rilis terfokus
  • general untuk pekerjaan berkelanjutan
  • ai untuk branch terisolasi tempat agen mengedit sumber daya tanpa menyentuh sumber utama

Saat perubahan siap, buat merge request alih-alih langsung menggabungkan ke branch utama:

# Ajukan endpoint yang berubah untuk ditinjau
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

Untuk mencadangkan spesifikasi setiap modul ke GitHub, GitLab, atau Azure DevOps, gunakan git-connection:

# Lihat opsi koneksi Git
apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

Output CLI berupa JSON terstruktur dengan agentHints.nextSteps, sehingga dapat digunakan dari skrip maupun agen AI. Untuk detail perintah, lihat panduan lengkap Apidog CLI.

Terbaik untuk: alur pembuatan versi, review, dan merge terintegrasi tanpa merangkai alat terpisah.

Batas jujur: ini adalah CLI platform dan berkomunikasi dengan proyek Apidog, bukan hanya file lokal biasa. Apidog CLI juga tidak menyediakan linter OpenAPI, jadi gunakan Redocly atau Spectral untuk aturan gaya. Jika tim memerlukan kontrol akses per peran, lihat kolaborasi API yang aman dengan RBAC.

Cara memilih

Pilih alat berdasarkan pekerjaan kolaborasi yang perlu Anda selesaikan.

Alat Terbaik untuk Instalasi Open source? Catatan
Git + file spesifikasi Riwayat dan review tanpa alat baru Sudah terinstal Ya (Git) Diff YAML bisa berisik
oasdiff Gerbang merge untuk perubahan breaking brew install oasdiff Ya (Apache 2.0) Kode keluar dapat menggagalkan CI
Optic Review perubahan terstruktur di PR npm i -g @useoptic/optic Ya (MIT) Memahami $ref, oneOf, dan lainnya
Bump.sh CLI Dokumentasi bersama dan diff npm i -g bump-cli CLI terbuka, hosting berbayar Membutuhkan Node 20+
Redocly CLI Lint, bundle, dan push ke registri npx @redocly/cli CLI terbuka, registri berbayar push membutuhkan API key
GitHub CLI Mengelola review PR dari shell brew install gh Ya (MIT) Tidak memahami semantik API
Apidog CLI Versi, review, dan merge terintegrasi npm i -g apidog-cli Tidak, tersedia tier gratis branch, merge-request, git-connection

Sebagian besar tim menggunakan kombinasi alat. Tumpukan ringan yang umum:

Git
  └── oasdiff atau Optic untuk semantic diff
        └── GitHub Actions atau CI sebagai gerbang merge
              └── Bump.sh atau Redocly untuk dokumentasi/registri
Enter fullscreen mode Exit fullscreen mode

Jika Anda ingin branch, review, dan merge dari satu CLI, Apidog mencakup ketiganya. Untuk membandingkan pilihan yang lebih luas, baca panduan alat tim kolaborasi API.

Penutup

Kolaborasi API dari terminal terdiri dari tiga langkah:

  1. Buat versi spesifikasi.
  2. Tinjau diff dan perubahan breaking.
  3. Gabungkan perubahan yang sudah disetujui.

Git menangani versi dan riwayat. oasdiff serta Optic memperjelas diff API. Bump.sh dan Redocly membantu menerbitkan hasilnya. GitHub CLI mengelola pull request. Apidog CLI menyatukan pembuatan versi, review, dan merge dalam satu rangkaian perintah.

Jika Anda ingin alur terintegrasi tanpa menyatukan banyak alat, unduh Apidog, instal apidog-cli, lalu buat branch dan merge request pertama Anda dari terminal.

Top comments (1)

Collapse
 
topstar_ai profile image
Luis •

Saya sangat setuju dengan pendekatan menggunakan Git sebagai fondasi untuk kolaborasi API, terutama dengan menyimpan file OpenAPI di repositori yang sama dengan kode aplikasi. Ini memungkinkan tim untuk menggunakan fitur Git seperti riwayat, branch, pull request, dan merge untuk mengelola perubahan spesifikasi API. Saya juga telah menggunakan oasdiff dalam proyek sebelumnya untuk membandingkan perubahan spesifikasi OpenAPI dan mendeteksi perubahan breaking, yang sangat membantu dalam memastikan kestabilan API. Bagaimana pengalaman Anda dengan menggunakan alat-alat CLI ringan untuk kolaborasi API, apakah ada rekomendasi atau tips yang dapat dibagikan?