Dokumentasi API menjadi usang begitu seseorang mengedit spesifikasi dan lupa untuk meregenerasi referensi. Solusinya adalah berhenti memperlakukan dokumentasi sebagai langkah manual. Jika Anda dapat menghasilkan dokumen dengan satu perintah, Anda dapat mengintegrasikan perintah tersebut ke CI dan membiarkannya berjalan setiap kali ada penggabungan.
Melakukannya dari terminal memiliki keuntungan lain. Perintah dapat diskrip, meninggalkan perbedaan (diff) yang dapat Anda tinjau, dan agen AI atau CI runner dapat memicunya tanpa ada yang membuka browser. Tidak ada klik GUI, tidak ada "apakah Anda ingat untuk menekan ekspor."
Panduan ini pertama-tama menjelaskan jalur umum yang terbuka: mengubah file OpenAPI menjadi referensi HTML mandiri atau file Markdown dengan satu perintah. Kemudian panduan ini membahas lebih dalam tentang jalur CLI Apidog, yang mengambil dokumen Anda langsung dari proyek yang sedang berjalan sehingga sumber kebenaran dan output tetap sinkron. Jika Anda ingin latar belakang lebih lanjut tentang lanskap ini, lihat rangkuman kami tentang alat dokumentasi API REST teratas dan alat dokumentasi API gratis yang patut Anda ketahui.
tombol
Anda memerlukan satu hal untuk mengikuti: file OpenAPI 3.x. Sebagian besar perintah ini menerima openapi.yaml atau openapi.json secara bergantian.
Buat referensi HTML dengan Redocly CLI
Redocly CLI adalah cara tercepat untuk mengubah deskripsi OpenAPI menjadi halaman HTML yang rapi dan mandiri. Ini merender spesifikasi Anda dengan Redoc dan menulis semuanya (gaya, skrip, dan konten) ke dalam satu file yang dapat Anda hosting di mana saja atau kirimkan melalui email kepada rekan tim.
Instal secara global, atau lewati instalasi dan jalankan dengan npx:
npm install @redocly/cli -g
Kemudian arahkan ke spesifikasi Anda:
redocly build-docs openapi.yaml
Secara default, ini menulis redoc-static.html di direktori saat ini. Buka file tersebut di browser dan Anda akan memiliki referensi API tiga panel lengkap. Untuk mengontrol nama file atau jalur, gunakan --output:
redocly build-docs openapi.yaml --output docs/index.html
Itulah seluruh alur kerja. Satu file input, satu perintah, satu artefak HTML. Ini berfungsi dengan deskripsi Swagger 2.0 dan OpenAPI 3.0/3.1, sehingga sebagian besar spesifikasi yang ada dirender tanpa perubahan. Komprominya adalah cakupan: build-docs memberi Anda halaman referensi dan tidak ada yang lain. Panduan panjang, tutorial, dan halaman memulai berada di luar itu.
Hasilkan Markdown dengan Widdershins
Terkadang Anda tidak menginginkan HTML. Anda ingin Markdown yang dapat Anda masukkan ke situs dokumen, generator situs statis, atau folder docs/ repositori. Widdershins mengonversi definisi OpenAPI, Swagger, atau AsyncAPI menjadi Markdown yang kompatibel dengan Slate.
Instal dari npm:
npm install -g widdershins
Kemudian konversi spesifikasi Anda, kirim output ke file dengan -o:
widdershins openapi.yaml -o api.md
Hilangkan -o dan Widdershins akan mencetak ke stdout, yang berguna jika Anda ingin mengalirkannya ke suatu tempat. Anda juga dapat mengaktifkan tab bahasa untuk contoh kode:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins sangat cocok ketika alur dokumen Anda mengutamakan Markdown. Jika Anda sedang membangun alur ekspor Markdown yang lebih luas, panduan kami tentang menggunakan generator dokumen API dengan ekspor Markdown mencakup peralatan di sekitarnya. Masalah dengan Redocly dan Widdershins adalah sama: keduanya membaca file statis. Jika definisi API Anda berada di alat desain dan menyimpang dari file di disk, Anda mendokumentasikan spesifikasi kemarin.
Dokumentasi dari proyek yang sedang berjalan dengan Apidog CLI
Di sinilah jalur terintegrasi membuahkan hasil. Apidog bukanlah sumber terbuka, tetapi tingkat gratisnya ditambah apidog-cli memberi Anda alternatif untuk menggabungkan alat-alat terpisah: endpoint, skema, dan dokumen tertulis Anda semuanya berada dalam satu proyek, dan CLI mengekspor dari proyek tersebut sesuai permintaan. Tidak ada yang menyimpang, karena ekspor membaca sumber yang sama yang diedit oleh tim Anda.
Instal CLI dari npm:
npm install -g apidog-cli
Jika Anda melakukan penyiapan untuk pertama kalinya, panduan instalasi Apidog CLI kami mencakup versi Node dan pengaturan PATH. Kemudian otentikasi sekali dengan token akses pribadi:
apidog login --with-token <TOKEN>
Token disimpan, jadi Anda tidak perlu meneruskannya di setiap panggilan. Dari sini, semuanya berjalan berdasarkan ID proyek. Tambahkan --help ke perintah apa pun untuk melihat flag pastinya sebelum Anda menjalankannya.
Impor spesifikasi ke dalam proyek
Jika API Anda sudah ada dalam file OpenAPI, bawa ke dalam proyek agar CLI memiliki sesuatu untuk diekspor:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import menerima format OpenAPI 3.x, Swagger 2.0, Postman, dan Apidog, sehingga Anda dapat menarik koleksi Postman atau ekspor Apidog yang ada dengan cara yang sama. Setelah spesifikasi diimpor, itu menjadi sumber langsung yang dibaca oleh yang lainnya.
Ekspor dokumen yang mudah dibaca manusia
Ini adalah perintah inti. apidog export menulis OpenAPI, HTML, Markdown, atau Postman, jadi jalankan --help terlebih dahulu untuk melihat format dan flag output yang tepat sesuai versi Anda, lalu ekspor dokumentasi proyek ke Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Buka api-docs.md dan Anda akan memiliki referensi lengkap yang dihasilkan dari status proyek saat ini. Ingin HTML sebagai gantinya? Ubah satu flag:
apidog export --project <projectId> --format html --output ./api-docs.html
Anda juga dapat mengekspor kembali ke OpenAPI ketika Anda ingin spesifikasi portabel untuk diserahkan ke hilir:
apidog export --project <projectId> --format openapi --output ./openapi.json
Jika proyek Anda berisi beberapa layanan dan Anda hanya ingin mendokumentasikan sebagian saja, ekspor mendukung pembatasan cakupan. Periksa apidog export --help untuk flag cakupan dan ID di versi Anda, karena satu proyek dapat mengirimkan satu file dokumen per layanan dengan cara tersebut.
Kelola panduan tertulis, bukan hanya referensi
Referensi yang dihasilkan dari skema Anda hanyalah setengah cerita. Separuh lainnya adalah tulisan: panduan memulai, panduan otentikasi, catatan migrasi. Di Apidog, dokumen-dokumen tersebut berada di pohon dokumen proyek sebagai dokumen Markdown, dan CLI mengelolanya dengan grup perintah doc.
Mulailah dengan membaca bantuan grup agar Anda bekerja dari flag yang tepat yang disediakan versi Anda:
apidog doc --help apidog doc list --project <projectId>
Dari sana, alurnya memiliki bentuk yang sama dengan yang lainnya di CLI: jalankan perintah terhadap proyek Anda, baca hasil JSON, dan ikuti agentHints.nextSteps yang dikembalikannya. Ketika suatu perintah membutuhkan payload JSON, CLI dapat mencetak skema yang diharapkan dan memvalidasi file Anda terhadapnya sebelum Anda mengirim apa pun, sehingga Anda mendeteksi bidang yang hilang di mesin Anda alih-alih dalam panggilan yang gagal. Periksa apidog cli-schema --help untuk subcommand validasi yang tepat.
Publikasikan situs dokumen
Ketika referensi dan panduan sudah siap, Anda juga dapat mengelola dokumentasi yang dipublikasikan dari terminal. Dua perintah mencakup hal itu, dan membaca bantuan mereka terlebih dahulu menghemat flag yang salah tebak:
apidog docs-site --help
apidog shared-doc --help
Satu catatan penamaan yang sering membingungkan orang: doc adalah dokumen Markdown di dalam pohon API proyek, docs-site mengelola situs dokumentasi publik yang di-hosting, dan shared-doc mengelola tautan dokumentasi yang dapat dibagikan. Gunakan docs-site ketika Anda ingin situs publik ditentukan dari terminal daripada diklik bersama di UI, dan shared-doc ketika Anda hanya ingin tautan untuk diserahkan kepada mitra. Keuntungannya adalah penerbitan menjadi langkah yang dapat diskrip: ketika spesifikasi Anda berubah, Anda mengimpor ulang atau mengedit proyek, lalu menjalankan perintah publikasi lagi, dan dokumen yang di-hosting mencerminkan pembaruan tersebut.
Integrasikan ke CI
Alasan untuk menjalankan semua ini dari CLI adalah untuk pengulangan. Setelah perintah berfungsi secara lokal, mereka akan berfungsi dalam pipeline. Langkah GitHub Actions minimal yang meregenerasi dan meng-commit referensi Markdown Anda pada setiap push terlihat seperti ini:
- name: Regenerate API docs
run: |
npm install -g apidog-cli
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Ganti dengan redocly build-docs atau widdershins dan bentuknya akan identik. Dokumen berhenti menjadi tugas yang diingat oleh seseorang untuk dilakukan dan menjadi artefak pembangunan yang meregenerasi dirinya sendiri. Untuk referensi perintah lengkap, lihat panduan lengkap Apidog CLI.
Masalah umum
ID proyek salah atau hilang. Setiap panggilan Apidog export, doc, dan docs-site memerlukan --project <projectId>. ID tersebut ada di pengaturan proyek, bukan nama proyek yang mudah dibaca. Jika sebuah perintah mengalami kesalahan yang mengeluhkan tentang proyek, itu hampir selalu menjadi penyebabnya.
Token tidak diatur di CI. apidog login menyimpan token di mesin yang menjalankannya. Dalam CI runner yang baru, tidak ada token yang tersimpan, jadi Anda harus menjalankan login --with-token di job yang sama sebelum melakukan ekspor apa pun. Simpan token sebagai rahasia, jangan pernah di file workflow.
Ekspor file usang. Redocly dan Widdershins membaca file apa pun yang Anda berikan kepada mereka. Jika openapi.yaml Anda kedaluwarsa, begitu juga dokumen Anda. Ini persis penyimpangan yang dihindari oleh rute Apidog dengan mengekspor dari proyek yang sedang berjalan, bukan dari file di disk.
Menebak flag alih-alih membaca --help. Flag yang tepat untuk export, doc, docs-site, dan shared-doc dapat bervariasi sesuai versi CLI. Jalankan apidog <command> --help dan gunakan apa yang dicetak daripada flag yang Anda setengah ingat. Ini membutuhkan dua detik dan menyelamatkan dari build yang gagal.
Kesimpulan
Mendokumentasikan API dari terminal bermuara pada pemilihan output yang tepat. Gunakan Redocly CLI saat Anda menginginkan referensi HTML mandiri, Widdershins saat Anda menginginkan Markdown untuk situs dokumen, dan Apidog CLI saat Anda menginginkan referensi ditambah panduan tertulis ditambah situs yang diterbitkan, semuanya diekspor dari satu sumber langsung. Opsi terakhir adalah yang menjaga dokumen Anda tetap jujur, karena ekspor dan hal yang diedit oleh tim Anda adalah proyek yang sama.
Setiap perintah di sini dapat diskrip, yang berarti setiap perintah tersebut harus ada di CI. Siapkan sekali dan dokumentasi Anda akan meregenerasi dirinya sendiri setiap kali ada perubahan. Unduh Apidog untuk mendapatkan CLI dan mencoba alur ekspor pada proyek Anda sendiri, atau baca lebih lanjut tentang bagaimana Apidog cocok dalam alur kerja yang mengutamakan API.
tombol