DEV Community

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

Posted on • Originally published at apidog.com

Alat CLI Ringan Terbaik untuk Desain API

Sebagian besar alat desain API lebih berat dari yang dibutuhkan pekerjaan sehari-hari. Jika Anda hanya ingin memeriksa aturan penamaan, menggabungkan spesifikasi yang terpisah, atau mendeteksi perubahan nama field yang merusak, Anda seharusnya cukup menjalankan satu perintah dari terminal—tanpa aplikasi desktop, layanan tambahan, atau konfigurasi panjang.

Coba Apidog hari ini

Artikel ini merangkum toolchain CLI ringan untuk desain API. Setiap alat dapat diinstal atau dijalankan dengan cepat, memiliki perintah yang bisa langsung dicoba, dan cocok dimasukkan ke CI. Untuk alur kerja desain yang lebih lengkap, baca panduan cara mendesain API, lalu pilih CLI yang sesuai dengan tahap kerja Anda.

Anda akan menggunakan enam alat untuk tugas berbeda:

  1. lint spesifikasi OpenAPI;
  2. bundel spesifikasi multi-file;
  3. menghasilkan SDK, stub server, dan dokumentasi;
  4. mendeteksi perubahan yang merusak antarversi;
  5. menjalankan lint dan diff dalam satu CLI;
  6. mendesain endpoint dan skema dari terminal dengan Apidog CLI.

Semua alat ini menggunakan Spesifikasi OpenAPI sebagai format bersama. Artinya, output dari satu alat dapat langsung menjadi input alat berikutnya.

Apa yang membuat alat CLI ringan untuk desain API

Ringan bukan berarti fiturnya sedikit. Dalam konteks desain API, alat CLI disebut ringan jika memenuhi tiga kriteria berikut.

  1. Instalasi kecil dan startup cepat

    Biner tunggal atau perintah npx lebih praktis dibanding alat yang membutuhkan runtime besar atau layanan aktif. Anda seharusnya dapat menjalankannya di container baru dalam beberapa menit.

  2. Konfigurasi minimal untuk hasil pertama

    Alat harus memberi output berguna saat langsung diarahkan ke file spesifikasi. Konfigurasi dan aturan kustom dapat ditambahkan setelah alur dasar berjalan.

  3. Terminal-first dan mudah di-script

    Alat ideal memiliki exit code yang jelas, output yang dapat dicari atau diproses, serta tidak bergantung pada GUI. Dengan begitu, perintah yang sama dapat berjalan di laptop dan pipeline pull request.

Urutan di bawah ini dimulai dari alat dengan jejak paling kecil dan adopsi tercepat.

Redocly CLI: lint dan bundel tanpa instalasi

Redocly CLI dapat dijalankan tanpa instalasi global. Cukup gunakan npx @redocly/cli@latest di depan perintah. Pendekatan ini cocok untuk CI, container sementara, atau pemeriksaan satu kali.

Redocly CLI berlisensi MIT dan paling berguna untuk dua pekerjaan: linting dan bundling.

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Gunakan bundle saat spesifikasi Anda dipecah menjadi beberapa file menggunakan $ref.

Contoh struktur proyek:

api/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── schemas/
    ├── User.yaml
    └── Error.yaml
Enter fullscreen mode Exit fullscreen mode

Jalankan bundling sebelum mengirim spesifikasi ke generator SDK, mock server, atau situs dokumentasi:

npx @redocly/cli@latest bundle api/openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Memecah spesifikasi berdasarkan resource membuat diff Git lebih mudah dibaca dan mengurangi konflik merge. Ini sejalan dengan alur kerja desain API Git-native.

Terbaik untuk: bundling spesifikasi multi-file dan validasi cepat tanpa instalasi.

Batasan: aturan lint bawaan lebih ringan daripada ruleset kustom penuh. Banyak tim menggunakan Redocly untuk bundling dan Spectral untuk penegakan gaya yang lebih ketat.

Spectral: linter gaya yang fleksibel

Spectral dari Stoplight adalah linter open-source untuk deskripsi API, berlisensi Apache-2.0. Spectral mendukung OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, dan Arazzo.

Instal dan jalankan lint dasar:

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

Tanpa ruleset kustom, Spectral menggunakan ruleset oas bawaan untuk menemukan masalah seperti:

  • deskripsi yang hilang;
  • contoh yang tidak valid;
  • struktur OpenAPI yang tidak sesuai;
  • field penting yang tidak tersedia.

Untuk menjadikannya panduan gaya yang dapat dieksekusi, tambahkan file .spectral.yaml di root repository:

extends:
  - spectral:oas

rules:
  operation-operationId:
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  path-kebab-case:
    given: $.paths
    then:
      function: casing
      functionOptions:
        type: kebab
Enter fullscreen mode Exit fullscreen mode

Lalu jalankan:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dengan ruleset ini, setiap endpoint wajib memiliki operationId, dan path dapat dipaksa mengikuti konvensi penamaan tim. Ini adalah cara praktis mengubah prinsip-prinsip desain API menjadi pemeriksaan otomatis.

Terbaik untuk: menegakkan panduan gaya API tim sebagai kode.

Batasan: Spectral memeriksa satu spesifikasi dan tidak membandingkan dua versi. Gunakan alat diff untuk mendeteksi perubahan yang merusak.

oasdiff: mendeteksi perubahan yang merusak sebagai biner tunggal

Linter dapat memberi tahu apakah satu file OpenAPI valid, tetapi tidak dapat memberi tahu apakah perubahan terbaru merusak klien yang sudah berjalan di produksi.

oasdiff mengisi celah tersebut. Ini adalah biner Go tunggal berlisensi Apache-2.0, tanpa runtime tambahan. Anda dapat memasangnya menggunakan Homebrew, unduhan rilis, atau Go.

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

Perintah utama yang perlu diketahui:

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

# Daftar semua perubahan yang mudah dibaca manusia
oasdiff changelog old-openapi.yaml new-openapi.yaml

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

Tambahkan pemeriksaan berikut ke CI agar pull request gagal ketika kontrak API berubah secara tidak kompatibel:

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

Contoh GitHub Actions sederhana:

name: Check OpenAPI breaking changes

on:
  pull_request:

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

      - name: Install oasdiff
        run: go install github.com/oasdiff/oasdiff@latest

      - name: Check breaking changes
        run: oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: mencegah perubahan yang merusak di CI dengan konfigurasi minimal.

Batasan: hasilnya bergantung pada disiplin tim menjaga spesifikasi tetap sesuai dengan API aktual. oasdiff juga bukan linter gaya, jadi jalankan bersama Spectral atau Redocly.

Optic: lint dan diff dalam satu CLI dengan peringatan

Optic berlisensi MIT dan menggabungkan linting serta diff OpenAPI dalam satu alat.

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

Namun, ada catatan penting: repositori publik Optic diarsipkan pada Januari 2026 dan proyek ini tidak lagi dipelihara. Kode sumber MIT-nya masih dapat digunakan, tetapi tidak ada aturan baru atau patch keamanan yang akan datang.

Jika Anda memulai pipeline baru, gunakan oasdiff untuk deteksi perubahan yang merusak. Optic tetap relevan untuk dipahami karena Anda mungkin menemukannya pada pipeline lama.

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

Batasan: tidak lagi dipelihara sejak awal 2026; perlakukan sebagai alat warisan dan rencanakan migrasi.

openapi-generator: mengubah desain menjadi klien dan stub

Desain API belum benar-benar siap dipakai sampai konsumen dapat membangun integrasi di atasnya. openapi-generator adalah proyek Apache-2.0 yang menghasilkan SDK klien, stub server, dan dokumentasi dari spesifikasi OpenAPI.

Ini adalah alat terberat dalam daftar karena berjalan di JVM, tetapi wrapper CLI membuat pemakaian hariannya tetap sederhana.

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 nilai -g sesuai target Anda:

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

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

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

Jalankan generator di CI setiap kali spesifikasi berubah. Dengan begitu, SDK klien tidak menyimpang dari kontrak API.

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o packages/api-client
Enter fullscreen mode Exit fullscreen mode

Menjadikan spesifikasi sebagai sumber kebenaran dan menghasilkan artefak lain darinya adalah inti dari pengembangan API yang mengutamakan desain.

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

Batasan: membutuhkan JDK 11 atau lebih baru. Kode hasil generator biasanya merupakan titik awal yang perlu disesuaikan, dan kualitas generator berbeda antarbahasa.

Apidog CLI: mendesain endpoint dan skema dari terminal

Lima alat sebelumnya memeriksa atau mengubah spesifikasi yang sudah ada. Apidog menangani tahap sebelumnya: mendesain endpoint dan skema data dari baris perintah.

Bagian ringannya adalah biner apidog-cli, bukan aplikasi desktop lengkap. Instal dari npm:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Login dengan token, lalu lihat endpoint dan skema yang tersedia:

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog schema list
Enter fullscreen mode Exit fullscreen mode

Ekspor hasil desain ke OpenAPI untuk diproses oleh toolchain lain:

apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

CLI menyediakan grup perintah untuk:

  • endpoint;
  • schema;
  • security-scheme;
  • folder;
  • mock;
  • import;
  • export.

Contoh alur terminal:

# 1. Ekspor desain dari Apidog
apidog export --format openapi -o openapi.yaml

# 2. Lint kontrak API
spectral lint openapi.yaml

# 3. Bundel bila spesifikasi menggunakan banyak file
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. Cek perubahan yang merusak
oasdiff breaking old-openapi.yaml dist/openapi.yaml

# 5. Hasilkan SDK
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Output CLI berbentuk JSON terstruktur dan menyertakan agentHints.nextSteps, sehingga mudah diteruskan ke skrip atau langkah otomatis lainnya. Lihat panduan lengkap Apidog CLI untuk daftar perintah lengkap.

Apidog bukan linter OpenAPI dan tidak menggantikan Spectral atau Redocly untuk penegakan aturan gaya. Apidog juga bukan open source; ini adalah produk komersial dengan tingkatan gratis. Perannya dalam toolchain adalah menyediakan tempat terintegrasi untuk mendesain endpoint dan skema, lalu mengekspor OpenAPI untuk diproses oleh alat lain.

Terbaik untuk: mendesain endpoint dan mengekspor spesifikasi dari satu tempat.

Batasan: bukan linter dan bukan open source; gunakan sebagai pelengkap alat validasi dan diff.

Cara memilih

Sebagian besar tim tidak hanya memakai satu alat. Pilih alat berdasarkan tahap kerja API Anda.

Alat Terbaik untuk Instalasi Open source? Catatan
Redocly CLI Bundling dan lint cepat npx @redocly/cli@latest Ya (MIT) Tanpa instalasi via npx; ideal untuk spesifikasi multi-file
Spectral Linting panduan gaya npm i -g @stoplight/spectral-cli Ya (Apache-2.0) Mulai tanpa konfigurasi; mendukung aturan kustom
oasdiff Deteksi perubahan yang merusak go install github.com/oasdiff/oasdiff@latest Ya (Apache-2.0) Biner Go tunggal; dipelihara
Optic Lint dan diff dalam satu alat npm i -g @useoptic/optic Ya (MIT) Repo diarsipkan Januari 2026; alat warisan
openapi-generator Generasi SDK, stub, dan dokumentasi npm i -g @openapitools/openapi-generator-cli Ya (Apache-2.0) Membutuhkan JDK 11+; paling berat dalam daftar
Apidog CLI Desain endpoint dan ekspor spesifikasi npm i -g apidog-cli Tidak (tingkat gratis) Bukan linter; mendesain dan mengekspor OpenAPI

Rekomendasi stack praktis

Untuk pipeline ringan yang bisa langsung diterapkan:

# Desain dan ekspor OpenAPI
apidog export --format openapi -o openapi.yaml

# Tegakkan aturan gaya
spectral lint openapi.yaml

# Bundel jika spesifikasi terdiri dari banyak file
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# Blokir perubahan yang merusak
oasdiff breaking old-openapi.yaml dist/openapi.yaml

# Hasilkan SDK bila diperlukan
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Untuk konteks perkakas yang lebih luas di luar CLI, baca alternatif Swagger untuk desain dan pengujian API serta panduan cara mendesain REST API.

Kesimpulan

Toolchain CLI ringan untuk desain API harus cepat dijalankan, mudah dimasukkan ke CI, dan fokus pada satu tugas.

  • Gunakan Redocly CLI untuk bundling dan lint cepat tanpa instalasi.
  • Gunakan Spectral untuk menegakkan panduan gaya tim.
  • Gunakan oasdiff untuk memblokir perubahan kontrak yang merusak.
  • Gunakan openapi-generator untuk menghasilkan SDK, stub, atau dokumentasi.
  • Kenali Optic sebagai opsi warisan pada pipeline lama.
  • Gunakan Apidog CLI untuk mendesain endpoint dan skema, lalu ekspor OpenAPI ke pipeline yang sama.

Jika Anda ingin mendesain endpoint dan skema di satu tempat sebelum menjalankan lint, diff, dan code generation, unduh Apidog dan coba apidog-cli. Ini melengkapi pemeriksaan open-source dalam pipeline Anda, bukan menggantikan linter.

Top comments (0)