Saat Anda memilih alat untuk menghasilkan dokumentasi API Anda, lisensi adalah bagian dari keputusan. Generator sumber terbuka berarti Anda dapat membaca kode, menghosting sendiri keluarannya, membuat fork jika macet, dan tidak pernah terkena batasan jumlah pengguna atau paywall pada fitur yang sudah Anda rilis. Untuk pekerjaan yang berjalan di setiap build CI, hal itu sama pentingnya dengan kualitas output.
Daftar ini adalah kumpulan alat dokumentasi API sumber terbuka yang berjalan dari baris perintah. Setiap alat di sini tersedia sumbernya di bawah lisensi asli, MIT atau Apache 2.0, di-host di GitHub, dan gratis untuk dijalankan tanpa akun. Anda mengarahkannya ke file OpenAPI atau Swagger dan ia akan memberikan Anda Markdown, halaman HTML statis, atau situs dokumentasi lengkap yang Anda miliki dan host sendiri.
Saya akan menandai lisensi yang tepat dan kisah self-hosting untuk setiap alat, karena itulah alasan utama Anda membaca rangkuman sumber terbuka alih-alih yang umum. Jika Anda menginginkan bidang yang lebih luas, rangkuman alat dokumentasi REST API teratas juga mencakup platform GUI. Spesifikasi OpenAPI adalah format yang dibaca oleh setiap alat di bawah ini, jadi spesifikasi yang valid adalah titik awal Anda.
Satu catatan jujur di awal. Apidog muncul di dekat akhir, dan itu bukan entri sumber terbuka; itu adalah platform freemium komersial. Saya menyertakannya hanya sebagai catatan sampingan berlabel untuk kasus di mana alat-alat sumber terbuka meninggalkan celah, dan saya akan eksplisit mengenai batasan tersebut.
Apa yang Membuat Alat Dokumentasi CLI “Sumber Terbuka”
Sumber terbuka bukan hanya “gratis untuk diunduh.” Untuk alat dokumentasi yang akan Anda integrasikan ke dalam build, tiga hal menentukan apakah alat tersebut benar-benar milik Anda.
Lisensi asli. MIT atau Apache 2.0 berarti Anda dapat menggunakan, memodifikasi, dan mendistribusikan ulang alat tersebut secara komersial tanpa perlu meminta izin. Keduanya disetujui oleh OSI. Apache 2.0 menambahkan hibah paten eksplisit, yang lebih disukai oleh beberapa tim hukum. Setiap alat di bawah ini memiliki salah satu dari keduanya.
Output yang dapat di-hosting sendiri. Tujuan dari dokumentasi sumber terbuka adalah bahwa tidak ada yang bergantung pada server vendor. Alat-alat ini menulis file statis: Markdown yang Anda commit, satu halaman HTML, atau folder berisi HTML/CSS/JS. Anda meng-host-nya di GitHub Pages, S3, atau server Nginx biasa, dan itu akan terus berfungsi terlepas dari apakah proyek di balik alat tersebut masih berjalan atau tidak.
Pemeliharaan dan komunitas. Sumber terbuka hanya membantu jika kode tersebut aktif. Jumlah bintang, komit terbaru, dan isu yang terbuka memberi tahu Anda apakah fork akan layak jika Anda membutuhkannya. Beberapa alat di sini telah diarsipkan tetapi masih berfungsi; saya akan mengatakannya.
Untuk sudut pandang tanpa biaya di seluruh opsi sumber terbuka dan freemium, daftar alat dokumentasi API gratis adalah artikel pelengkap. Sekarang mari kita bahas alat-alatnya.
Redocly CLI
Redocly CLI adalah cara tercepat untuk mengubah spesifikasi menjadi referensi HTML yang rapi dan mandiri. Ini berlisensi MIT dan open core: CLI serta mesin rendering Redoc di bawahnya adalah sumber terbuka di GitHub, sementara beberapa fitur portal yang di-host ada dalam produk berbayar Redocly. Perintah build-docs sepenuhnya berada di bagian sumber terbuka.
npx @redocly/cli build-docs openapi.yaml -o api-docs.html
Itu menulis satu file HTML yang dibangun di atas Redoc. Buka secara lokal, letakkan di host statis mana pun, atau lampirkan ke rilis. Tidak ada yang mengirim data kembali, dan Anda dapat menjalankannya secara offline setelah paket di-cache.
Terbaik dalam: referensi API satu halaman yang bersih dari satu perintah, berlisensi MIT dan di-host sendiri. Batasan jujur: keluarannya adalah satu halaman, jadi ini lebih merupakan referensi daripada portal multi-halaman, dan theming yang lebih kaya ada di tingkatan berbayar. Jika Anda membandingkan mesin rendering satu sama lain, perbandingan alternatif Redocly menjelaskan di mana batas sumber terbuka berada.
Widdershins
Widdershins adalah konverter murni di bawah lisensi MIT. Ini membaca OpenAPI 3, Swagger 2, atau AsyncAPI dan mengeluarkan Markdown; itulah seluruh tugasnya. Karena keluarannya adalah Markdown biasa, Anda sepenuhnya memilikinya: commit, bandingkan dalam pull request, atau masukkan ke situs statis apa pun yang sudah Anda jalankan.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Markdown yang ditulisnya kompatibel dengan Slate, yang menyandingkannya dengan rapi dengan generator situs nanti dalam daftar ini. Flag yang berguna: --omitHeader menghilangkan front-matter, dan --language_tabs memilih bahasa contoh kode.
Terbaik dalam: memasukkan konten spesifikasi ke dalam Markdown yang dapat dikontrol versinya tanpa ikatan vendor. Batasan jujur: Markdown adalah semua yang Anda dapatkan. Tidak ada styling dan tidak ada situs yang dirender, jadi Widdershins adalah setengah dari sebuah pipeline; sesuatu yang lain mengubah Markdown menjadi halaman.
OpenAPI Generator
OpenAPI Generator berlisensi Apache 2.0 dan dijalankan oleh komunitas, di-fork dari Swagger Codegen pada tahun 2018. Ini paling dikenal untuk SDK klien, tetapi juga menyediakan generator dokumentasi: generator markdown menulis folder Markdown, dan html2 menulis satu halaman HTML mandiri.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Lisensi Apache 2.0 dan hibah patennya membuatnya mudah disetujui oleh tim hukum yang berhati-hati, dan proyek ini adalah salah satu yang paling aktif dipelihara di bidang ini.
Terbaik dalam: menggunakan kembali satu alat untuk SDK dan dokumentasi, di bawah lisensi permisif dengan dukungan komunitas yang kuat. Batasan jujur: pembungkus npm masih mengunduh jar Java pada saat pertama kali dijalankan, jadi ini bukan binary tunggal, dan output yang ditemplat bersifat sederhana. Jika Anda hanya membutuhkan dokumentasi, konverter yang lebih ringan tersedia.
Swagger Codegen
Swagger Codegen adalah generator berbasis template asli dari tim Swagger, berlisensi Apache 2.0. Ini mendahului fork OpenAPI Generator dan masih dikelola oleh SmartBear. Untuk dokumentasi, ia menawarkan dua jalur: html untuk referensi statis satu halaman dan dynamic-html untuk situs interaktif kecil.
npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Kedua proyek ini berbagi DNA dan banyak opsi, jadi jika tim Anda sudah membakukan pada toolchain Swagger, ini akan membuat Anda tetap menggunakannya.
Terbaik dalam: tim yang sudah berinvestasi dalam ekosistem Swagger yang menginginkan dokumentasi dari alat Apache 2.0 yang sama yang menghasilkan stubs mereka. Batasan jujur: ini didukung Java seperti OpenAPI Generator, dan pengembangannya bergerak lebih lambat daripada fork komunitas. Untuk sebagian besar pengaturan baru, OpenAPI Generator adalah pilihan yang lebih aktif; Swagger Codegen unggul dalam kontinuitas.
Docusaurus dengan Plugin OpenAPI
Jika satu halaman HTML tidak cukup dan Anda menginginkan situs dokumentasi yang nyata dan bervariasi, Docusaurus adalah landasan sumber terbuka. Ini berlisensi MIT, dibangun oleh Meta, dan salah satu generator situs statis yang paling banyak digunakan di web. Sendiri, ia merender Markdown dan MDX; plugin docusaurus-openapi-docs, juga MIT dan dikelola oleh Palo Alto Networks, menambahkan generasi spesifikasi-ke-dokumen.
npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
Setelah mengkonfigurasi plugin dengan jalur spesifikasi Anda, gen-api-docs mengubah file OpenAPI menjadi halaman MDX yang dirender di dalam situs Docusaurus, lengkap dengan panel "coba" dan navigasi bilah sisi.
Terbaik dalam: portal dokumentasi lengkap yang di-host sendiri dengan versi, pencarian, dan panduan tulisan tangan di samping referensi yang dihasilkan. Batasan jujur: ini adalah pengaturan terberat di sini. Anda menyiapkan situs React dan langkah build, jadi ini berlebihan jika yang Anda butuhkan hanyalah halaman referensi. Untuk itu, Redocly CLI adalah jalur yang lebih pendek.
Slate
Slate adalah tata letak dokumentasi API tiga kolom klasik: navigasi di kiri, prosa di tengah, contoh kode di kanan, semuanya dirender sebagai situs statis. Ini berlisensi Apache 2.0 dan ditenagai oleh Middleman, jadi memerlukan toolchain Ruby. Tidak seperti konverter di atas, Slate tidak membaca OpenAPI secara langsung; Anda menulis Markdown, dan Slate merendernya.
# after cloning your Slate fork and running bundle install
bundle exec middleman build
Itu menulis situs statis lengkap ke folder build/ yang bisa Anda host di mana saja. Di sinilah Widdershins berperan: konversikan spesifikasi Anda ke Markdown, lalu biarkan Slate merendernya ke dalam tata letak yang dikenal itu.
Terbaik dalam: dokumentasi naratif yang dikurasi secara manual di mana Anda ingin kontrol editorial atas struktur dan prosa, pada situs statis yang sepenuhnya di-host sendiri. Batasan jujur: repo asli diarsipkan (pemelihara mundur), meskipun masih dapat dibangun dan fork aktif, dan dependensi Ruby lebih berat daripada satu baris perintah npx. Jika dokumentasi Anda meregenerasi langsung dari spesifikasi, konverter lebih ringan.
Apidog CLI (catatan jujur, bukan entri sumber terbuka)
Semua alat di atas adalah sumber terbuka, dan masing-masing mencakup satu bagian: mengkonversi, merender, atau menghosting file statis. Kesenjangan yang mereka tinggalkan adalah proyek langsung. Jika API Anda bukan hanya satu file YAML tetapi proyek yang dikelola dengan endpoint, skema, dan contoh, Anda akan berakhir dengan menghubungkan konverter, perender, dan host secara manual dan menjaga ketiganya tetap sinkron.
Itulah celah yang diisi oleh binary apidog-cli. Untuk bersikap lugas tentang lisensinya: Apidog bukan sumber terbuka. Ini adalah platform freemium komersial dengan tingkatan gratis, dan CLI berkomunikasi dengan proyek yang di-host daripada spesifikasi lokal. Saya menyertakannya di sini hanya agar perbandingan jujur tentang apa yang dapat dan tidak dapat dilakukan oleh alat sumber terbuka, bukan sebagai opsi sumber terbuka.
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 ekspor mengubah proyek menjadi Markdown atau HTML tanpa pipeline build, dan apidog doc serta apidog docs-site mengelola sumber daya dokumentasi dari sebuah skrip. Outputnya adalah JSON terstruktur, sehingga mudah diintegrasikan ke dalam CI atau agen. Panduan lengkap Apidog CLI menjelaskan otentikasi dan setiap grup perintah. Jika alur kerja ekspor Markdown adalah yang Anda cari, artikel generator dokumen API dengan ekspor Markdown akan membahas lebih dalam.
Di mana batasnya: alat sumber terbuka memberi Anda kode yang Anda miliki, file yang Anda host sendiri, dan tidak ada ketergantungan vendor. Apidog memberi Anda satu rute terintegrasi dari proyek yang dikelola ke dokumentasi yang dapat dibagikan, dengan biaya menjadi produk freemium yang di-host. Pilih berdasarkan apakah sumber kebenaran Anda adalah spesifikasi statis atau proyek langsung.
Cara memilih
Sesuaikan lisensi dan output dengan apa yang perlu dimiliki 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 Anda commit | npm i -g widdershins |
Ya (MIT) | Markdown |
| OpenAPI Generator | Dokumentasi ditambah SDK, satu alat | npm i -g @openapitools/openapi-generator-cli |
Ya (Apache 2.0) | Markdown atau HTML |
| Swagger Codegen | Tim yang terstandardisasi 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 secara manual | Ruby + Bundler | Ya (Apache 2.0) | Situs statis |
| Apidog CLI | Ekspor dari proyek langsung | npm i -g apidog-cli |
Tidak (freemium) | Markdown atau HTML |
Singkatnya: untuk spesifikasi dasar dan referensi HTML yang dapat dibagikan, gunakan Redocly CLI. Untuk Markdown yang Anda kontrol versinya, Widdershins. Jika Anda sudah menghasilkan SDK, OpenAPI Generator juga menghasilkan dokumentasi, dan Swagger Codegen mencakup Anda jika Anda sudah terstandardisasi pada Swagger. Ketika Anda menginginkan portal nyata dengan versi dan panduan, Docusaurus ditambah plugin OpenAPI adalah landasan sumber terbuka, dan Slate adalah pilihan untuk dokumentasi tulisan tangan yang dikontrol secara editorial. Setiap alat ini tersedia sumbernya dan dapat di-host sendiri, jadi tidak ada yang Anda rilis bergantung pada vendor yang tetap beroperasi. Untuk pandangan tanpa biaya yang lebih luas, rangkuman alat dokumentasi API gratis menyatukan opsi sumber terbuka dan freemium.
Kesimpulan
Memilih CLI dokumentasi sumber terbuka bermuara pada lisensi, output, dan tempat dokumentasi Anda berada. MIT dan Apache 2.0 keduanya memungkinkan Anda menggunakan, memodifikasi, dan menghosting sendiri tanpa biaya per pengguna, jadi pilihlah alat terkecil yang menghasilkan output yang Anda butuhkan: Redocly CLI untuk satu halaman, Widdershins untuk Markdown, OpenAPI Generator atau Swagger Codegen untuk dokumentasi di samping SDK Anda, Docusaurus untuk portal, Slate untuk halaman yang dikurasi secara manual.
Jika API Anda berada dalam proyek yang dikelola daripada file yang terpisah, dan Anda lebih suka mengekspor dokumentasi daripada menggabungkan tiga alat, Unduh Apidog dan coba apidog export terhadap sebuah proyek. Ini dapat dimasukkan ke dalam pekerjaan CI sehingga dokumentasi Anda dibangun kembali setiap kali API berubah, hanya saja perlu diingat bahwa ini adalah platform freemium, bukan binary sumber terbuka.