Alat CLI Ringan Terbaik untuk Dokumentasi API

Anda memiliki file OpenAPI dan Anda menginginkan dokumen darinya. Anda tidak ingin menyiapkan layanan, masuk ke portal, atau menambahkan langkah build yang menarik setengah dari npm. Anda ingin satu perintah yang membaca spesifikasi dan memberi Anda file Markdown atau satu halaman HTML yang dapat Anda host di mana saja.

Itulah gunanya daftar ini. Setiap alat di sini kecil: satu biner, satu baris npx, atau paket yang Anda instal sekali dan lupakan. Mereka memulai dengan cepat, membutuhkan sedikit atau tanpa konfigurasi, dan melakukan tugas dokumentasi tanpa menyeret platform penuh di belakangnya. Beberapa mengeluarkan Markdown yang Anda masukkan ke situs dokumen yang sudah ada. Beberapa mengeluarkan file HTML mandiri. Semuanya berjalan di CI dan di terminal, itulah intinya.

Jika Anda menginginkan bidang platform dokumentasi yang lebih luas, ringkasan alat dokumentasi REST API terbaik mencakup bagian yang banyak GUI. Artikel ini adalah potongan yang mengutamakan terminal, dengan jejak kecil. Untuk referensi resmi tentang apa yang dibaca oleh generator dokumentasi, Spesifikasi OpenAPI adalah sumber kebenaran yang diuraikan oleh setiap alat di bawah ini.

Apa yang Membuat Alat CLI "Ringan" untuk Dokumentasi API

Ringan bukan berarti kurang bertenaga. Ini tentang jejak dan gesekan. Empat hal yang menentukannya.

Ukuran instalasi dan dependensi. Satu biner atau satu paket npm mengalahkan kerangka kerja. Jika menghasilkan halaman dokumen berarti menginstal runtime bahasa ditambah bundler ditambah sistem plugin, itu tidak ringan, apa pun tampilan keluarannya.

Startup dan konfigurasi. Yang terbaik dari ini membaca spesifikasi Anda dan menghasilkan keluaran tanpa konfigurasi. Anda mengarahkan perintah ke openapi.yaml dan mendapatkan kembali sebuah file. Apa pun yang membutuhkan file konfigurasi sebelum dapat berjalan sama sekali akan kehilangan poin di sini.

Keluaran tujuan tunggal. Setiap alat di bawah ini melakukan satu hal: spesifikasi masuk, dokumen keluar. Markdown atau HTML, tidak ada hal lain yang terpasang. Itulah yang membuat mereka cepat dan dapat diprediksi dalam sebuah pipeline.

Berjalan di mana saja. Tidak ada GUI, tidak ada login untuk alat terbuka, tidak ada server yang harus tetap aktif. Ia berfungsi di laptop Anda dan berfungsi dengan cara yang sama dalam pekerjaan CI. Untuk pilihan bebas biaya yang lebih luas, daftar alat dokumentasi API gratis memiliki platformnya; ini adalah potongan CLI dari itu.

Sekarang alat-alatnya, dari yang terkecil terlebih dahulu.

Widdershins

Widdershins adalah sekecil ini. Ini adalah paket npm tunggal yang mengubah file OpenAPI 3, Swagger 2, atau AsyncAPI menjadi Markdown. Itu seluruh pekerjaannya. Ia tidak merender situs atau menjalankan server; ia memberi Anda file .md dan kemudian selesai.

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

Markdown yang dihasilkannya kompatibel dengan Slate, yang penting jika Anda berencana untuk memasukkannya ke situs statis nanti. Flag yang berguna: --omitHeader menghilangkan front-matter YAML, dan --language_tabs mengontrol bahasa contoh kode mana yang ditampilkan.

Terbaik dalam: mendapatkan konten spesifikasi ke dalam Markdown yang dapat Anda commit, diff, dan masukkan ke sistem dokumen apa pun. Batasan jujur: Markdown adalah semua yang Anda dapatkan. Tidak ada gaya, tidak ada panel "coba" interaktif, dan tidak ada output yang di-host. Widdershins adalah konverter, bukan perender, jadi Anda memasangkannya dengan sesuatu yang mengubah Markdown menjadi situs.

OpenAPI Generator (generator dokumen)

OpenAPI Generator paling dikenal untuk SDK klien, tetapi juga menyediakan generator dokumentasi, dan itu berguna ketika spesifikasi adalah satu-satunya yang Anda miliki. Generator markdown menulis folder Markdown; generator html2 menulis satu halaman HTML mandiri. Anda dapat menjalankannya melalui wrapper npm tanpa perlu menginstal Java sendiri.

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/

Wrapper npm masih mengunduh jar yang didukung JDK di baliknya, jadi lebih berat daripada Widdershins pada saat pertama kali dijalankan. Setelah itu, ini adalah perintah sekali jalan untuk menghasilkan.

Terbaik dalam: menggunakan kembali alat yang mungkin sudah Anda jalankan untuk SDK agar juga mengeluarkan dokumen, dengan pilihan antara Markdown dan HTML mandiri. Batasan jujur: keluarannya sederhana dan digerakkan oleh template, dan pemanggilan pertama menarik jar, jadi ini bukan benar-benar biner tunggal. Jika Anda hanya membutuhkan dokumen dan tidak ada yang lain, ada pilihan yang lebih ringan.

Redocly CLI (build-docs)

Jika Anda menginginkan halaman HTML mandiri yang menarik dari satu perintah, Redocly CLI adalah jalur terpendek. Perintah build-docs menggabungkan spesifikasi Anda menjadi satu file HTML mandiri yang dibangun di atas Redoc. Tanpa server, tanpa build hosting terpisah; Anda mendapatkan file yang dapat Anda buka, kirim email, atau letakkan di host statis mana pun.

npx @redocly/cli build-docs openapi.yaml

Secara default ia menulis redoc-static.html. Ubah nama dengan --output:

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

Karena ia berjalan melalui npx, Anda bahkan tidak perlu menginstalnya secara global untuk mencobanya. Terbaik dalam: referensi satu halaman yang dipoles dari satu perintah, dengan tema default yang bersih dan tanpa perlu mengelola cerita hosting. Batasan jujur: keluarannya adalah satu file HTML, jadi ini adalah halaman referensi daripada portal dokumen multi-halaman, dan tema serta pratinjau yang lebih kaya ada di tingkatan berbayar Redocly. Jika Anda membandingkannya dengan perender serupa, perbandingan alternatif Redocly dan alternatif Scalar menjelaskan trade-off-nya.

Slate

Slate adalah yang paling berbeda di sini: ia bukan konverter spesifikasi ke dokumen, ia adalah generator situs statis untuk dokumen API yang ditulis tangan. Anda menulis Markdown, dan Slate membangun tata letak dokumen tiga kolom klasik (navigasi, konten, dan contoh kode berdampingan) menjadi situs statis mandiri. Ia didukung oleh Middleman, jadi ia membutuhkan Ruby.

# setelah mengkloning repo slate dan menginstal dependensi
bundle exec middleman build

Itu menulis situs statis lengkap ke folder build/ yang dapat Anda host di mana saja. Di sinilah Widdershins terbayar: hasilkan Markdown dari spesifikasi Anda, lalu biarkan Slate merendernya, dan Anda mendapatkan konten berbasis spesifikasi dalam tata letak Slate.

Terbaik dalam: dokumen API naratif yang dikurasi secara manual di mana Anda menginginkan kontrol editorial atas struktur dan prosa. Batasan jujur: ini adalah pilihan terberat dalam daftar ini karena membutuhkan toolchain Ruby, dan ia tidak membaca OpenAPI sendiri; Anda memberinya Markdown. Jika dokumen Anda dihasilkan langsung dari spesifikasi dan jarang diedit secara manual, konverter saja lebih ringan.

Apidog CLI (ekspor + dokumen)

Alat-alat terbuka di atas masing-masing mencakup satu bagian: konversi, render, atau host. Jika API Anda sudah ada dalam proyek alih-alih file YAML tunggal, menyatukannya adalah gesekan. Di situlah biner apidog-cli cocok. Ini adalah pendamping baris perintah untuk Apidog, dan satu ekspor mengubah proyek menjadi Markdown atau HTML tanpa pipeline build.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

Kemudian ekspor dokumentasi proyek ke Markdown atau HTML dalam satu perintah:

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

CLI juga mengelola sumber daya dokumen secara langsung. apidog doc menangani dokumen Markdown proyek, dan apidog docs-site mengelola situs dokumentasi yang diterbitkan, sehingga Anda dapat mencantumkan, membuat, dan memperbarui dokumen dari skrip atau pekerjaan CI:

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

Keluaran adalah JSON terstruktur, yang membuatnya mudah untuk disalurkan ke langkah lain atau diberikan kepada agen. Untuk permukaan perintah lengkap, panduan lengkap Apidog CLI membahas otentikasi, proyek, dan setiap grup perintah.

Berikut adalah penjelasan jujur. Apidog bukanlah sumber terbuka, dan bukan biner tujuan tunggal; ini adalah platform freemium, dan CLI berbicara dengan proyek yang di-host. Ia juga tidak melinting OpenAPI Anda atau memberlakukan panduan gaya; Redocly dan Spectral melakukan itu. Yang diberikan CLI kepada Anda adalah satu rute terintegrasi dari proyek API yang terkelola ke Markdown atau HTML yang dapat dibagikan, alih-alih merangkai konverter, perender, dan host secara manual. Jika Anda menginginkan jalur ekspor Markdown secara khusus, artikel generator dokumen API dengan ekspor Markdown membahas alur kerja tersebut lebih dalam.

Cara memilih

Cocokkan alat dengan bentuk input Anda dan output yang Anda butuhkan.

Singkatnya: jika Anda memiliki spesifikasi kosong dan menginginkan Markdown untuk di-commit, gunakan Widdershins. Jika Anda menginginkan satu halaman HTML yang dapat dibagikan, redocly build-docs adalah yang tercepat. Jika Anda menulis dokumen secara manual dan menginginkan tata letak yang tepat, Slate. Dan jika API Anda sudah ada dalam proyek dan Anda menginginkan ekspor plus manajemen dokumen dalam satu CLI, Apidog. Untuk gambaran umum tanpa biaya di seluruh bidang, ringkasan alat dokumentasi API gratis menyatukannya.

Kesimpulan

Perkakas dokumentasi yang ringan bermuara pada satu aturan: pilih hal terkecil yang menghasilkan keluaran yang Anda butuhkan. Widdershins dan redocly build-docs mencakup sebagian besar kasus spesifikasi-ke-dokumen dalam satu perintah. OpenAPI Generator layak digunakan ketika Anda sudah menghasilkan SDK. Slate layak dengan jejaknya yang lebih berat hanya ketika Anda menulis dokumen secara manual. Dan ketika API Anda berada dalam proyek nyata daripada file yang terpisah, ekspor apidog-cli memberi Anda Markdown atau HTML tanpa pipeline.

Jika kasus terakhir itu adalah Anda, Unduh Apidog dan coba apidog export terhadap proyek; itu masuk dengan rapi ke dalam pekerjaan CI sehingga dokumen Anda dibangun kembali setiap kali API berubah.