Alat CLI Open Source Gratis untuk Dokumentasi API

Saat memilih alat untuk menghasilkan dokumentasi API, lisensi adalah bagian penting dari keputusan. Generator sumber terbuka memungkinkan Anda membaca kode, meng-host output sendiri, membuat fork jika proyek berhenti, serta menghindari batas pengguna atau paywall pada fitur yang sudah dirilis. Untuk dokumentasi yang dibangun di setiap pipeline CI, hal ini sama pentingnya dengan kualitas output.

Coba Apidog hari ini

Daftar ini berisi alat dokumentasi API sumber terbuka yang dapat dijalankan dari command line. Setiap alat tersedia di GitHub dengan lisensi MIT atau Apache 2.0, gratis dijalankan tanpa akun, dan dapat mengubah file OpenAPI atau Swagger menjadi Markdown, HTML statis, atau situs dokumentasi lengkap yang Anda host sendiri.

Saya akan menandai lisensi dan opsi self-hosting setiap alat karena itulah alasan utama memilih rangkuman sumber terbuka. Jika Anda juga mempertimbangkan platform GUI, lihat alat dokumentasi REST API teratas. Semua alat di bawah membaca Spesifikasi OpenAPI, jadi mulai dari spesifikasi yang valid.

Satu catatan penting: Apidog muncul di bagian akhir, tetapi bukan alat sumber terbuka. Apidog adalah platform freemium komersial dan hanya disertakan sebagai pembanding ketika workflow sumber terbuka belum mencakup kebutuhan tertentu.

Apa yang Membuat Alat Dokumentasi CLI “Sumber Terbuka”

Sumber terbuka bukan sekadar “gratis untuk diunduh”. Untuk alat dokumentasi yang akan masuk ke proses build, periksa tiga hal berikut.

1. Lisensi permisif

Lisensi MIT atau Apache 2.0 memungkinkan Anda menggunakan, memodifikasi, dan mendistribusikan ulang alat secara komersial tanpa meminta izin tambahan. Keduanya disetujui OSI.

Apache 2.0 juga menyertakan hibah paten eksplisit, yang sering menjadi pertimbangan tim legal. Semua alat sumber terbuka dalam daftar ini menggunakan salah satu lisensi tersebut.

2. Output dapat di-host sendiri

Dokumentasi sumber terbuka seharusnya tidak bergantung pada server vendor. Alat-alat berikut menghasilkan file statis, misalnya:

• Markdown yang dapat di-commit ke repository
• Satu file HTML mandiri
• Folder berisi HTML, CSS, dan JavaScript

Anda dapat meng-host output tersebut di GitHub Pages, S3, Nginx, atau static hosting lain. Dokumentasi tetap berjalan meskipun proyek pembuat tool sudah tidak aktif.

3. Pemeliharaan dan komunitas

Kode sumber hanya berguna jika masih dapat dipelihara. Sebelum memilih alat, periksa aktivitas commit, issue terbuka, dan keberadaan fork aktif. Beberapa proyek di bawah telah diarsipkan, tetapi masih berfungsi dan dapat digunakan melalui fork.

Untuk membandingkan opsi sumber terbuka dan freemium tanpa biaya, lihat alat dokumentasi API gratis.

Redocly CLI

Redocly CLI adalah salah satu cara tercepat untuk mengubah spesifikasi OpenAPI menjadi referensi HTML mandiri. Tool ini berlisensi MIT dan menggunakan model open core: CLI serta mesin rendering Redoc bersifat sumber terbuka, sementara beberapa fitur portal yang di-host tersedia dalam produk berbayar Redocly.

Untuk membuat dokumentasi dari file OpenAPI:

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

Perintah tersebut menghasilkan satu file api-docs.html. Anda dapat membukanya secara lokal, mengunggahnya ke static host, atau menyertakannya sebagai artefak rilis.

Contoh pipeline CI:

- name: Build API docs
  run: npx @redocly/cli build-docs openapi.yaml -o public/api-docs.html

Terbaik untuk: referensi API satu halaman yang rapi, cepat dibuat, berlisensi MIT, dan mudah di-host sendiri.

Batasan: output utamanya berupa satu halaman, sehingga lebih cocok sebagai referensi daripada portal dokumentasi multi-halaman. Opsi theming yang lebih kaya tersedia di tier berbayar. Untuk membandingkan renderer, lihat alternatif Redocly.

Widdershins

Widdershins adalah konverter MIT yang membaca OpenAPI 3, Swagger 2, atau AsyncAPI lalu menghasilkan Markdown. Fokusnya hanya satu: mengubah spesifikasi menjadi dokumentasi Markdown yang dapat Anda versioning.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Karena output-nya Markdown biasa, Anda dapat:

1. Commit hasilnya ke repository.
2. Meninjau perubahan dokumentasi melalui pull request.
3. Merendernya dengan generator situs statis seperti Slate atau Docusaurus.
4. Menambahkan narasi manual sebelum atau sesudah bagian yang dihasilkan.

Beberapa flag yang berguna:

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

# Tentukan tab bahasa untuk contoh kode
widdershins openapi.yaml \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md

Terbaik untuk: pipeline spesifikasi-ke-Markdown yang dapat dikontrol versinya tanpa ketergantungan vendor.

Batasan: Widdershins hanya menghasilkan Markdown. Anda tetap membutuhkan renderer atau static site generator untuk mengubah Markdown menjadi situs dokumentasi.

OpenAPI Generator

OpenAPI Generator berlisensi Apache 2.0 dan dikelola komunitas. Proyek ini di-fork dari Swagger Codegen pada 2018.

Walaupun terkenal sebagai generator SDK klien, OpenAPI Generator juga menyediakan generator dokumentasi:

• markdown untuk menghasilkan folder Markdown
• html2 untuk menghasilkan halaman HTML mandiri

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

# Generate dokumentasi Markdown
openapi-generator-cli generate \
  -g markdown \
  -i openapi.yaml \
  -o docs/

# Generate dokumentasi HTML
openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/

Contoh untuk workflow yang juga menghasilkan SDK:

openapi-generator-cli generate -g typescript-fetch -i openapi.yaml -o sdk/
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

Lisensi Apache 2.0 dan hibah patennya membuat tool ini sering lebih mudah disetujui oleh tim legal. Proyeknya juga termasuk yang paling aktif di ekosistem OpenAPI.

Terbaik untuk: tim yang ingin menghasilkan SDK dan dokumentasi dari satu toolchain.

Batasan: wrapper npm mengunduh JAR Java pada penggunaan pertama. Output template dokumentasinya juga cukup sederhana jika dibandingkan dengan renderer yang lebih fokus pada tampilan.

Swagger Codegen

Swagger Codegen adalah generator berbasis template dari tim Swagger, berlisensi Apache 2.0, dan masih dikelola oleh SmartBear.

Untuk dokumentasi, dua generator yang relevan adalah:

• html untuk referensi statis satu halaman
• dynamic-html untuk situs interaktif sederhana

npm install -g swagger-codegen-cli

swagger-codegen-cli generate \
  -i openapi.yaml \
  -l html \
  -o docs/

Jika tim Anda sudah menggunakan toolchain Swagger untuk menghasilkan server stub atau SDK, Swagger Codegen menjaga workflow tetap konsisten.

Terbaik untuk: tim yang sudah terstandardisasi pada ekosistem Swagger dan menginginkan dokumentasi dari tool Apache 2.0 yang sama.

Batasan: seperti OpenAPI Generator, tool ini membutuhkan Java. Pengembangannya juga lebih lambat dibandingkan fork komunitas OpenAPI Generator. Untuk proyek baru, OpenAPI Generator biasanya merupakan pilihan yang lebih aktif; Swagger Codegen lebih cocok untuk menjaga kontinuitas toolchain yang sudah ada.

Docusaurus dengan Plugin OpenAPI

Jika satu halaman HTML tidak cukup dan Anda membutuhkan portal dokumentasi lengkap, Docusaurus adalah fondasi sumber terbuka yang kuat. Docusaurus berlisensi MIT, dibuat oleh Meta, dan banyak digunakan untuk situs dokumentasi statis.

Docusaurus sendiri merender Markdown dan MDX. Untuk menghasilkan halaman dari OpenAPI, gunakan plugin docusaurus-openapi-docs, yang juga berlisensi MIT dan dikelola oleh Palo Alto Networks.

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

npm run docusaurus gen-api-docs all

Setelah plugin dikonfigurasi dengan path spesifikasi Anda, gen-api-docs mengubah OpenAPI menjadi halaman MDX yang dirender dalam situs Docusaurus. Hasilnya dapat mencakup sidebar, navigasi, panel “coba”, dokumentasi versi, serta panduan yang ditulis manual.

Contoh workflow:

# Regenerasi halaman API dari spesifikasi
npm run docusaurus gen-api-docs all

# Jalankan situs lokal
npm run start

# Build static site untuk deployment
npm run build

Terbaik untuk: portal dokumentasi self-hosted yang lengkap, dengan versioning, pencarian, panduan, dan referensi API dalam satu situs.

Batasan: ini adalah setup paling berat dalam daftar. Anda perlu memelihara situs React serta langkah build. Jika hanya membutuhkan halaman referensi API, Redocly CLI adalah jalur yang lebih singkat.

Slate

Slate menyediakan layout dokumentasi API tiga kolom klasik:

• Navigasi di sebelah kiri
• Konten naratif di tengah
• Contoh kode di sebelah kanan

Slate berlisensi Apache 2.0 dan menggunakan Middleman, sehingga membutuhkan toolchain Ruby. Tidak seperti tool sebelumnya, Slate tidak membaca OpenAPI secara langsung. Anda menulis atau menghasilkan Markdown terlebih dahulu, lalu Slate merendernya menjadi situs statis.

# Setelah clone fork Slate dan menjalankan bundle install
bundle exec middleman build

Hasil build ditulis ke folder build/, yang dapat di-host di static hosting mana pun.

Pipeline umum untuk menggabungkan Widdershins dan Slate:

# 1. Ubah spesifikasi OpenAPI menjadi Markdown
widdershins openapi.yaml -o source/index.html.md

# 2. Build situs Slate
bundle exec middleman build

Terbaik untuk: dokumentasi naratif yang dikurasi secara manual, dengan kontrol editorial penuh terhadap struktur dan prosa.

Batasan: repository asli telah diarsipkan, walaupun masih dapat dibangun dan terdapat fork aktif. Dependensi Ruby juga lebih berat daripada perintah npx tunggal. Jika dokumentasi harus diregenerasi langsung dari spesifikasi, konverter yang lebih ringan biasanya lebih praktis.

Apidog CLI (Catatan Jujur, Bukan Entri Sumber Terbuka)

Semua alat di atas adalah sumber terbuka, tetapi masing-masing biasanya menangani satu bagian dari pipeline: mengonversi spesifikasi, merender halaman, atau meng-host file statis.

Kesenjangan muncul ketika sumber dokumentasi Anda bukan file YAML tunggal, melainkan proyek API yang dikelola dengan endpoint, schema, dan contoh. Dalam kondisi tersebut, Anda mungkin perlu menghubungkan konverter, renderer, dan hosting secara manual sambil menjaga semuanya tetap sinkron.

Binary apidog-cli ditujukan untuk workflow tersebut. Namun, penting untuk jelas mengenai lisensinya: Apidog bukan sumber terbuka. Ini adalah platform freemium komersial dengan tier gratis, dan CLI berkomunikasi dengan proyek yang di-host, bukan hanya spesifikasi lokal.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md

apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html

Satu perintah ekspor dapat mengubah proyek menjadi Markdown atau HTML tanpa merakit pipeline build terpisah. Perintah apidog doc dan apidog docs-site juga dapat mengelola resource dokumentasi dari skrip.

Output CLI berupa JSON terstruktur, sehingga dapat diintegrasikan ke CI atau agen otomatisasi. Lihat panduan lengkap Apidog CLI untuk autentikasi dan grup perintah. Jika fokus Anda adalah ekspor Markdown, lihat generator dokumen API dengan ekspor Markdown.

Batasnya jelas:

• Alat sumber terbuka: Anda memiliki kode, meng-host output sendiri, dan tidak bergantung pada vendor.
• Apidog: menyediakan jalur terintegrasi dari proyek yang dikelola ke dokumentasi yang dapat dibagikan, tetapi merupakan produk freemium yang di-host.

Pilih berdasarkan sumber kebenaran API Anda: spesifikasi statis atau proyek API yang dikelola langsung.

Cara Memilih

Sesuaikan lisensi, format output, dan kompleksitas setup dengan kebutuhan tim Anda.

Alat	Terbaik untuk	Instalasi	Sumber terbuka?	Output
Redocly CLI	Satu halaman HTML yang rapi	npx @redocly/cli	Ya (MIT, open core)	HTML mandiri
Widdershins	Spesifikasi ke Markdown yang di-commit	npm i -g widdershins	Ya (MIT)	Markdown
OpenAPI Generator	Dokumentasi dan SDK dari satu tool	npm i -g @openapitools/openapi-generator-cli	Ya (Apache 2.0)	Markdown atau HTML
Swagger Codegen	Tim yang terstandardisasi pada Swagger	npm i -g swagger-codegen-cli	Ya (Apache 2.0)	HTML
Docusaurus + Plugin OpenAPI	Situs dokumentasi lengkap yang di-host sendiri	npx create-docusaurus	Ya (MIT)	Situs statis
Slate	Dokumentasi tiga kolom yang dikurasi manual	Ruby + Bundler	Ya (Apache 2.0)	Situs statis
Apidog CLI	Ekspor dari proyek API yang dikelola	npm i -g apidog-cli	Tidak (freemium)	Markdown atau HTML

Ringkasnya:

• Gunakan Redocly CLI untuk referensi HTML statis yang cepat dibagikan.
• Gunakan Widdershins untuk Markdown yang dapat di-versioning.
• Gunakan OpenAPI Generator jika Anda juga menghasilkan SDK.
• Gunakan Swagger Codegen jika toolchain Anda sudah berbasis Swagger.
• Gunakan Docusaurus + Plugin OpenAPI untuk portal dokumentasi lengkap.
• Gunakan Slate untuk dokumentasi editorial yang dikurasi manual.
• Gunakan Apidog CLI jika dokumentasi perlu diekspor dari proyek API yang dikelola.

Semua opsi sumber terbuka di atas dapat di-host sendiri, sehingga dokumentasi yang Anda rilis tidak bergantung pada vendor yang tetap beroperasi. Untuk pilihan gratis yang lebih luas, lihat alat dokumentasi API gratis.

Kesimpulan

Memilih CLI dokumentasi API sumber terbuka bergantung pada tiga hal: lisensi, output, dan lokasi sumber dokumentasi Anda.

Lisensi MIT dan Apache 2.0 sama-sama memungkinkan penggunaan, modifikasi, dan self-hosting tanpa biaya per pengguna. Karena itu, pilih tool paling sederhana yang menghasilkan output yang Anda butuhkan:

• Redocly CLI untuk satu halaman HTML.
• Widdershins untuk Markdown.
• OpenAPI Generator atau Swagger Codegen untuk dokumentasi bersama SDK.
• Docusaurus untuk portal dokumentasi.
• Slate untuk halaman yang dikurasi secara manual.

Jika API Anda berada dalam proyek yang dikelola, bukan file spesifikasi terpisah, dan Anda lebih memilih ekspor dokumentasi daripada menggabungkan beberapa tool, unduh Apidog lalu coba apidog export pada proyek Anda. Perintah tersebut dapat dimasukkan ke pekerjaan CI agar dokumentasi dibangun ulang setiap kali API berubah—dengan catatan bahwa Apidog adalah platform freemium, bukan binary sumber terbuka.