DEV Community

Cover image for Alat CLI Open Source Gratis untuk Desain API
Walse
Walse

Posted on • Originally published at apidog.com

Alat CLI Open Source Gratis untuk Desain API

Desain API dimulai dari berkas spesifikasi, jauh sebelum kode diluncurkan. Aturan gaya yang terlewat, perubahan yang merusak, atau skema yang menyimpang dari rilis sebelumnya akan lebih mahal diperbaiki setelah API digunakan. Dengan CLI, Anda dapat menangkap masalah tersebut langsung dari terminal dan menjalankannya secara konsisten di CI tanpa bergantung pada antarmuka pengguna.

Coba Apidog hari ini

Artikel ini berfokus pada toolchain desain API sumber terbuka. Semua alat di bawah memiliki lisensi terbuka, dapat dijalankan tanpa biaya per kursi, dapat di-self-host, dan versinya dapat dikunci di repositori Anda. Ini penting ketika spesifikasi API disimpan di Git dan pemeriksaan harus menghasilkan output yang sama di laptop developer maupun pipeline CI. Untuk konteks desain API yang lebih luas, baca panduan cara mendesain API.

Anda akan menggunakan enam alat untuk tugas berbeda:

  • linting aturan gaya dan kualitas spesifikasi;
  • linting cepat dengan ruleset Spectral;
  • bundling spesifikasi multi-berkas;
  • generasi SDK, stub server, dan dokumentasi;
  • deteksi perubahan yang merusak antarversi spesifikasi.

Semua alat menggunakan Spesifikasi OpenAPI, sehingga output dari satu tahap dapat digunakan langsung oleh tahap berikutnya.

Catatan tentang Apidog: Apidog dibahas sebagai pelengkap, tetapi bukan perangkat lunak sumber terbuka dan bukan linter OpenAPI. Apidog adalah produk komersial dengan tingkat gratis. Toolchain sumber terbuka utama dalam artikel ini adalah Spectral, vacuum, Redocly CLI, openapi-generator, oasdiff, dan Optic.

Apa yang membuat CLI desain API benar-benar sumber terbuka?

Istilah sumber terbuka bukan sekadar label. Untuk daftar ini, alat harus memenuhi tiga kriteria berikut.

  1. Lisensi terbuka yang jelas

    Lisensi harus dapat dibaca dan digunakan secara legal, seperti MIT atau Apache-2.0. Lisensi tersebut memungkinkan penggunaan dalam proyek komersial tanpa biaya lisensi atau batas jumlah kursi.

  2. Dapat dijalankan sendiri dan dikunci versinya

    Anda harus dapat menyematkan versi biner atau paket tertentu, lalu menjalankannya secara offline di runner CI. Pekerjaan inti alat tidak boleh bergantung pada akun atau koneksi ke layanan eksternal.

  3. Masih memiliki pemeliharaan dan komunitas

    Periksa aktivitas commit, isu yang ditanggapi, rilis, dan changelog. Proyek berlisensi MIT tetap bisa menjadi pilihan buruk jika tidak lagi dipelihara.

Setiap alat di bawah dipilih berdasarkan kriteria tersebut. Jika status pemeliharaannya terbatas atau proyeknya diarsipkan, itu disebutkan secara eksplisit.

Spectral: linter gaya OpenAPI yang fleksibel

Spectral dari Stoplight adalah linter referensi untuk deskripsi API. Alat ini berlisensi Apache-2.0 dan mendukung OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, serta Arazzo.

Gunakan Spectral jika tim Anda memiliki panduan gaya API yang ingin dijadikan aturan yang dapat dieksekusi.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Secara default, Spectral menyediakan ruleset oas untuk mendeteksi masalah seperti:

  • description yang hilang;
  • contoh respons yang tidak valid;
  • struktur OpenAPI yang tidak sesuai;
  • referensi atau skema yang bermasalah.

Nilai utamanya ada pada aturan kustom. Contohnya, buat berkas .spectral.yaml untuk mewajibkan operationId pada setiap operasi:

extends:
  - spectral:oas

rules:
  require-operation-id:
    description: Setiap operasi harus memiliki operationId
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Kemudian jalankan linting dengan ruleset tersebut:

spectral lint openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Simpan ruleset di repositori agar semua kontributor dan pipeline CI menerapkan standar yang sama.

Terbaik untuk: menegakkan panduan gaya API sebagai kode.

Batasan: Spectral hanya memeriksa satu versi spesifikasi. Gunakan alat diff seperti oasdiff untuk mendeteksi perubahan yang merusak.

vacuum: linter cepat yang kompatibel dengan ruleset Spectral

Jika Spectral adalah standar linting, vacuum adalah opsi berperforma tinggi. vacuum ditulis dengan Go, berlisensi MIT, dan kompatibel dengan ruleset Spectral.

Artinya, Anda dapat memakai aturan Spectral yang sudah ada tanpa perlu menulis ulang.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Flag -d menampilkan output detail untuk setiap aturan yang dilanggar.

Untuk menggunakan ruleset kustom Spectral:

vacuum lint -d --ruleset .spectral.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuum juga dapat menghasilkan laporan HTML dan dokumentasi dari spesifikasi yang sama. Karena didistribusikan sebagai biner terkompilasi tanpa runtime Node.js, alat ini cocok untuk:

  • hook pre-commit;
  • pipeline CI dengan waktu eksekusi ketat;
  • kontainer minimal;
  • spesifikasi OpenAPI besar.

Terbaik untuk: linting cepat pada spesifikasi besar menggunakan ruleset Spectral yang sudah ada.

Batasan: ekosistem aturan dan dokumentasi masih banyak berpusat pada Spectral. Anda biasanya tetap menulis aturan menggunakan model Spectral.

Redocly CLI: lint dan bundle dalam satu alur

Redocly CLI berlisensi MIT. Selain linting, fitur utamanya adalah bundle, yaitu menggabungkan spesifikasi OpenAPI multi-berkas dengan $ref menjadi satu dokumen.

Ini berguna ketika struktur repositori Anda seperti berikut:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas.yaml
    └── responses.yaml
Enter fullscreen mode Exit fullscreen mode

Instal dan jalankan:

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Berkas sumber yang dipisah per resource membuat perubahan lebih mudah ditinjau dan konflik merge lebih kecil. Ini adalah praktik penting dalam alur kerja desain API Git-native.

Gunakan hasil bundling sebagai artefak tunggal untuk:

  • validasi CI;
  • server mock;
  • generasi SDK;
  • publikasi dokumentasi;
  • pemeriksaan perubahan dengan oasdiff.

Contoh pipeline sederhana:

redocly lint openapi/openapi.yaml
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
oasdiff breaking main-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: spesifikasi multi-berkas yang membutuhkan bundling dan validasi.

Batasan: aturan lint default lebih ringan daripada ruleset Spectral kustom. Banyak tim memakai Redocly untuk bundling, lalu Spectral atau vacuum untuk penegakan gaya mendalam.

openapi-generator: menghasilkan SDK, stub server, dan dokumentasi

openapi-generator berlisensi Apache-2.0 dan dapat menghasilkan SDK klien, stub server, serta dokumentasi dari spesifikasi OpenAPI dalam banyak bahasa.

Pendekatan ini menjadikan spesifikasi sebagai sumber kebenaran. Kode turunan dibuat ulang dari kontrak, bukan ditulis dan dipelihara secara terpisah. Ini selaras dengan pendekatan schema-first dan contract-driven yang dibahas dalam prinsip-prinsip desain API.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Ganti target generator sesuai kebutuhan:

# Go client
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python client
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java client
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

Jalankan generator di CI setiap kali spesifikasi berubah:

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client

git diff --exit-code generated/client
Enter fullscreen mode Exit fullscreen mode

Pemeriksaan git diff --exit-code membantu memastikan kode hasil generate tidak tertinggal dari kontrak API.

Terbaik untuk: menjaga SDK, stub, dan dokumentasi tetap selaras dengan spesifikasi.

Batasan: membutuhkan JDK 11+, output generator sering perlu disesuaikan, dan kualitas generator berbeda antarbahasa. Selalu tinjau output sebelum digunakan di produksi.

oasdiff: mendeteksi perubahan yang merusak sebelum rilis

Linter dapat memeriksa kualitas satu spesifikasi, tetapi tidak dapat mengetahui apakah perubahan baru merusak klien yang sudah ada. oasdiff adalah alat Go berlisensi Apache-2.0 untuk membandingkan dua versi OpenAPI dan menandai perubahan yang merusak.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Gunakan perintah yang sesuai dengan kebutuhan:

# Hanya perubahan yang merusak
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Changelog yang mudah dibaca
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Delta lengkap yang dapat dibaca mesin
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Contoh integrasi pada pull request:

redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
oasdiff breaking main-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Jika oasdiff breaking menemukan perubahan seperti penghapusan endpoint, field wajib yang berubah, atau respons yang tidak lagi kompatibel, buat job CI gagal.

Terbaik untuk: mencegah perubahan yang merusak di CI.

Batasan: oasdiff hanya membandingkan spesifikasi. Jika spesifikasi tidak mencerminkan API produksi, hasil pemeriksaannya juga tidak akan akurat. Gunakan bersama Spectral atau vacuum untuk linting gaya.

Optic: lint dan diff dalam satu CLI, dengan peringatan pemeliharaan

Optic berlisensi MIT dan menggabungkan linting serta diff OpenAPI dalam satu alat. Ia dapat membandingkan dua versi spesifikasi untuk menemukan perubahan yang merusak, menerapkan aturan gaya, dan menghasilkan spesifikasi dari lalu lintas pengujian yang diamati.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Namun, status pemeliharaan perlu diperhatikan: repositori publik Optic diarsipkan pada awal 2026 dan proyek ini tidak lagi dipelihara secara aktif.

Kode sumber MIT masih dapat digunakan dan disematkan ke pipeline yang ada, tetapi Anda tidak akan mendapatkan aturan baru atau patch keamanan. Untuk deteksi perubahan yang merusak pada proyek baru, oasdiff adalah opsi yang lebih terpelihara.

Terbaik untuk: tim yang sudah menggunakan Optic atau membutuhkan lint dan diff dalam satu CLI.

Batasan: tidak lagi dipelihara sejak awal 2026. Perlakukan sebagai alat warisan dan siapkan rencana migrasi.

Di mana Apidog cocok, dan di mana tidak

Apidog bukan perangkat lunak sumber terbuka dan bukan linter OpenAPI. Untuk linting serta penegakan aturan gaya, gunakan Spectral, vacuum, atau Redocly CLI.

Apidog menawarkan trade-off berbeda: platform terintegrasi untuk mendesain endpoint dan skema data, lalu mengekspor hasilnya sebagai OpenAPI agar dapat diperiksa oleh toolchain sumber terbuka.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Setelah diekspor, jalankan pemeriksaan yang sama:

spectral lint openapi.yaml
oasdiff breaking previous-openapi.yaml openapi.yaml
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

CLI Apidog menyediakan grup perintah untuk endpoint, schema, mock, serta import dan export. Lihat panduan lengkap Apidog CLI untuk daftar perintah lengkap.

Pembingkaian yang tepat: Apidog adalah opsi komersial terintegrasi yang dapat bekerja bersama toolchain sumber terbuka. Ini bukan pengganti linter dan bukan proyek sumber terbuka.

Bagaimana memilih toolchain

Pilih alat berdasarkan tahap kerja. Dalam praktiknya, kebanyakan tim menjalankan dua hingga empat alat berikut bersama-sama.

Alat Terbaik untuk Instalasi Sumber terbuka? Catatan
Spectral Linting panduan gaya npm i -g @stoplight/spectral-cli Ya (Apache-2.0) Linter referensi untuk aturan kustom
vacuum Linting cepat dalam skala besar brew install --cask daveshanley/vacuum/vacuum Ya (MIT) Menjalankan ruleset Spectral dengan performa tinggi
Redocly CLI Bundling + validasi npm i -g @redocly/cli Ya (MIT) Cocok untuk spesifikasi $ref multi-berkas
openapi-generator SDK, stub, dan dokumentasi npm i -g @openapitools/openapi-generator-cli Ya (Apache-2.0) Membutuhkan JDK 11+
oasdiff Deteksi perubahan merusak go install github.com/oasdiff/oasdiff@latest Ya (Apache-2.0) Cocok sebagai pemeriksaan pull request
Optic Lint + diff dalam satu alat npm i -g @useoptic/optic Ya (MIT) Repositori diarsipkan pada awal 2026
Apidog CLI Desain dan ekspor terintegrasi npm i -g apidog-cli Tidak (tingkat gratis) Bukan linter; mengekspor OpenAPI

Rekomendasi stack praktis

Untuk kebanyakan proyek OpenAPI, gunakan urutan berikut:

# 1. Lint aturan gaya
spectral lint openapi/openapi.yaml --ruleset .spectral.yaml

# 2. Bundle spesifikasi multi-berkas
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml

# 3. Cegah perubahan merusak
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 4. Generate SDK dari kontrak yang sudah lolos pemeriksaan
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Ringkasnya:

  • gunakan Spectral atau vacuum untuk gaya;
  • gunakan Redocly CLI untuk bundling;
  • gunakan oasdiff untuk perubahan yang merusak;
  • gunakan openapi-generator untuk menghasilkan klien, stub, atau dokumentasi.

Jika Anda ingin mengeksplorasi ekosistem desain dan pengujian API di luar CLI, baca alternatif Swagger untuk desain dan pengujian API serta panduan cara mendesain API REST.

Ringkasan

Toolchain CLI sumber terbuka untuk desain API sudah matang dan dapat dijalankan tanpa biaya per kursi:

  • Spectral dan vacuum menangani linting;
  • Redocly CLI menangani bundling;
  • openapi-generator menghasilkan SDK, stub, dan dokumentasi;
  • oasdiff mendeteksi perubahan yang merusak;
  • Optic masih relevan untuk pipeline lama, tetapi sebaiknya diperlakukan sebagai alat warisan.

Hubungkan alat-alat tersebut ke CI agar kontrak API diperiksa pada setiap push, tanpa vendor lock-in dan tanpa pemeriksaan manual.

Jika Anda lebih nyaman mendesain endpoint dan skema dalam satu platform sebelum mengekspor OpenAPI ke pipeline yang sama, unduh Apidog dan gunakan apidog-cli. Apidog dapat menjadi pendamping komersial untuk stack sumber terbuka, bukan pengganti linter Anda.

Top comments (0)