DEV Community

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

Posted on • Originally published at apidog.com

Alat CLI Ringan Terbaik untuk Dokumentasi API

Anda memiliki file OpenAPI dan ingin mengubahnya menjadi dokumentasi tanpa menyiapkan layanan, masuk ke portal, atau menambahkan langkah build besar. Targetnya sederhana: jalankan satu perintah, baca spesifikasi, lalu hasilkan Markdown atau satu file HTML yang dapat di-host di mana saja.

Coba Apidog hari ini

Artikel ini membahas alat CLI dengan jejak kecil: satu biner, satu perintah npx, atau paket yang diinstal sekali. Semua alat di bawah dapat dijalankan dari terminal dan CI. Beberapa menghasilkan Markdown untuk dimasukkan ke situs dokumentasi yang sudah ada, sedangkan lainnya menghasilkan HTML mandiri.

Jika Anda membutuhkan platform dokumentasi yang lebih lengkap, lihat ringkasan alat dokumentasi REST API terbaik. Untuk memahami format input yang diproses generator-generator ini, gunakan Spesifikasi OpenAPI sebagai referensi utama.

Apa yang Membuat Alat CLI Ringan untuk Dokumentasi API

“Ringan” bukan berarti fiturnya terbatas. Yang dinilai adalah jejak instalasi dan jumlah gesekan saat dipakai dalam workflow.

  1. Instalasi dan dependensi kecil

    Satu paket npm atau satu biner lebih sederhana daripada runtime, bundler, dan plugin tambahan.

  2. Konfigurasi minimum

    Idealnya, alat cukup menerima openapi.yaml lalu menghasilkan file dokumentasi tanpa file konfigurasi awal.

  3. Keluaran dengan tujuan jelas

    Alurnya seharusnya langsung: spesifikasi masuk, dokumen keluar. Biasanya berupa Markdown atau HTML.

  4. Dapat dijalankan di mana saja

    Tidak perlu GUI, login, atau server yang aktif. Perintah yang sama harus bekerja di laptop maupun pipeline CI.

Untuk pilihan gratis yang lebih luas, lihat daftar alat dokumentasi API gratis. Berikut adalah opsi yang berfokus pada CLI.

Widdershins

Widdershins adalah opsi paling minimal untuk mengonversi OpenAPI 3, Swagger 2, atau AsyncAPI menjadi Markdown. Alat ini tidak merender situs dan tidak menjalankan server—hasil akhirnya hanya file .md.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Gunakan hasilnya sebagai artefak yang dapat di-commit dan di-review melalui diff Git.

Beberapa flag yang berguna:

# Hilangkan YAML front matter
widdershins openapi.yaml -o api-docs.md --omitHeader

# Tentukan tab bahasa contoh kode
widdershins openapi.yaml -o api-docs.md --language_tabs 'javascript:JavaScript' 'python:Python'
Enter fullscreen mode Exit fullscreen mode

Markdown hasil Widdershins kompatibel dengan Slate, sehingga Anda dapat menggunakan Widdershins sebagai tahap konversi sebelum membangun situs dokumentasi statis.

Terbaik untuk: mengubah spesifikasi menjadi Markdown secepat mungkin.

Batasan: tidak menyediakan gaya visual, panel interaktif “try it”, atau hosting. Anda perlu memasangkannya dengan renderer Markdown atau generator situs statis.

OpenAPI Generator: generator dokumentasi

OpenAPI Generator dikenal sebagai generator SDK, tetapi juga memiliki generator dokumentasi. Ini berguna jika Anda sudah memakai OpenAPI Generator untuk client SDK dan ingin menghasilkan dokumen dari spesifikasi yang sama.

npm install -g @openapitools/openapi-generator-cli

# Hasilkan folder Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# Hasilkan dokumentasi HTML
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

Wrapper npm mengunduh JAR berbasis JDK pada eksekusi pertama, sehingga startup awal lebih berat daripada Widdershins. Setelah dependensi tersedia, perintah generasinya tetap langsung dan dapat dipakai di CI.

Terbaik untuk: proyek yang sudah menggunakan OpenAPI Generator untuk SDK dan dokumentasi.

Batasan: output berbasis template dan eksekusi pertama mengunduh JAR. Jika hanya membutuhkan dokumen Markdown sederhana, Widdershins lebih ringan.

Redocly CLI: build-docs

Jika target Anda adalah satu halaman HTML mandiri yang rapi, Redocly CLI menyediakan jalur cepat melalui build-docs.

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Secara default, perintah tersebut menghasilkan redoc-static.html. Gunakan --output untuk menentukan nama file sendiri:

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

Karena dijalankan dengan npx, Anda tidak perlu menginstalnya secara global untuk mencoba. File HTML yang dihasilkan dapat dibuka secara lokal atau diunggah ke static hosting.

Contoh penggunaan dalam CI:

npx @redocly/cli build-docs openapi.yaml --output dist/api.html
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: referensi API satu halaman yang siap dibagikan atau di-host.

Batasan: outputnya berupa satu file HTML, bukan portal dokumentasi multi-halaman. Tema dan kemampuan pratinjau yang lebih kaya tersedia pada tingkatan berbayar Redocly.

Untuk membandingkan pendekatan ini dengan renderer lain, baca alternatif Redocly dan alternatif Scalar.

Slate

Slate berbeda dari alat sebelumnya. Slate bukan konverter OpenAPI ke dokumentasi, melainkan generator situs statis untuk dokumentasi API yang ditulis dalam Markdown.

Anda menulis atau menghasilkan Markdown, lalu Slate membangun tata letak klasik tiga kolom: navigasi, konten, dan contoh kode. Slate menggunakan Middleman, sehingga membutuhkan Ruby.

# Setelah meng-clone repo Slate dan menginstal dependensi
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Hasil build akan tersedia di folder build/, lalu dapat di-host sebagai situs statis.

Workflow yang umum:

openapi.yaml
  -> Widdershins
  -> api-docs.md
  -> Slate
  -> build/
Enter fullscreen mode Exit fullscreen mode

Terbaik untuk: dokumentasi API naratif yang membutuhkan kontrol editorial atas struktur, panduan, dan prosa.

Batasan: membutuhkan toolchain Ruby dan tidak membaca OpenAPI secara langsung. Jika dokumentasi selalu dihasilkan dari spesifikasi dan jarang diedit manual, gunakan konverter langsung saja.

Apidog CLI: ekspor dokumentasi proyek

Alat open-source sebelumnya biasanya menangani satu bagian: konversi atau rendering. Jika API Anda sudah dikelola sebagai proyek, bukan hanya file YAML tunggal, apidog-cli menyediakan jalur ekspor langsung dari proyek ke Markdown atau HTML.

apidog-cli adalah pendamping CLI untuk Apidog.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Ekspor dokumentasi proyek ke Markdown:

apidog export --project <projectId> --format markdown --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

Atau ekspor ke HTML:

apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

CLI juga menyediakan perintah untuk mengelola sumber daya dokumentasi dari skrip atau CI:

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Keluaran perintah berbentuk JSON terstruktur, sehingga dapat diteruskan ke langkah pipeline lain.

Contoh pola CI:

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format html \
  --output ./dist/api-docs.html
Enter fullscreen mode Exit fullscreen mode

Untuk daftar perintah lengkap, lihat panduan lengkap Apidog CLI.

Apidog bukan alat sumber terbuka atau biner tujuan tunggal. Ini adalah platform freemium dan CLI-nya bekerja dengan proyek yang di-host. CLI ini juga tidak menggantikan linter OpenAPI atau style guide seperti Redocly dan Spectral.

Namun, jika Anda memerlukan alur dari proyek API terkelola ke dokumen Markdown atau HTML tanpa merangkai konverter, renderer, dan hosting sendiri, pendekatan ini lebih terintegrasi. Untuk workflow Markdown secara khusus, baca generator dokumen API dengan ekspor Markdown.

Cara memilih

Pilih berdasarkan bentuk input dan output yang Anda butuhkan.

Alat Terbaik untuk Instalasi Sumber terbuka? Keluaran
Widdershins Spesifikasi ke Markdown dengan cepat npm i -g widdershins Ya, MIT Markdown
OpenAPI Generator Dokumentasi bersama SDK npm i -g @openapitools/openapi-generator-cli Ya, Apache 2.0 Markdown atau HTML
Redocly CLI Satu halaman HTML yang rapi npx @redocly/cli Ya, MIT, open core HTML mandiri
Slate Situs dokumentasi yang dikurasi manual Ruby + Bundler Ya, Apache 2.0 Situs statis
Apidog CLI Ekspor langsung dari proyek npm i -g apidog-cli Tidak, tersedia tingkat gratis Markdown atau HTML

Gunakan aturan praktis berikut:

  • Pilih Widdershins jika Anda memiliki spesifikasi dan ingin menghasilkan Markdown untuk di-commit.
  • Pilih Redocly CLI jika Anda membutuhkan satu file HTML yang langsung dapat dibagikan.
  • Pilih OpenAPI Generator jika proyek sudah menggunakannya untuk menghasilkan SDK.
  • Pilih Slate jika dokumentasi perlu ditulis dan dikurasi manual.
  • Pilih Apidog CLI jika API sudah ada di proyek Apidog dan Anda membutuhkan ekspor plus manajemen dokumentasi dalam satu CLI.

Untuk perbandingan pilihan gratis yang lebih luas, lihat alat dokumentasi API gratis.

Kesimpulan

Perkakas dokumentasi ringan mengikuti satu prinsip: gunakan alat terkecil yang menghasilkan format keluaran yang Anda butuhkan.

Widdershins dan redocly build-docs mencakup sebagian besar kebutuhan spesifikasi-ke-dokumen dalam satu perintah. OpenAPI Generator masuk akal jika Anda sudah menggunakannya untuk SDK. Slate layak dipakai ketika dokumentasi membutuhkan pengeditan manual dan struktur editorial. Jika API dikelola sebagai proyek, apidog-cli menyediakan ekspor Markdown atau HTML tanpa pipeline konversi terpisah.

Jika workflow terakhir sesuai dengan kebutuhan Anda, unduh Apidog dan coba apidog export pada proyek Anda. Perintah tersebut dapat dimasukkan ke pekerjaan CI agar dokumentasi dibangun ulang setiap kali API berubah.

Top comments (0)