DEV Community

Cover image for Cara Mendokumentasikan API dari CLI
Walse
Walse

Posted on • Originally published at apidog.com

Cara Mendokumentasikan API dari CLI

Dokumentasi API cepat usang ketika spesifikasi berubah tetapi referensi tidak diregenerasi. Jadikan dokumentasi sebagai bagian dari build: hasilkan dokumen dengan satu perintah, jalankan perintah itu di CI, dan perbarui artefak setiap kali perubahan digabungkan.

Coba Apidog hari ini

Menjalankannya dari terminal membuat proses ini mudah diotomatisasi, dapat ditinjau melalui diff, dan dapat dipicu oleh CI runner atau agen AI tanpa membuka browser. Tidak ada langkah GUI yang harus diingat.

Panduan ini membahas tiga jalur:

  1. Menghasilkan referensi HTML mandiri dari file OpenAPI dengan Redocly CLI.
  2. Menghasilkan Markdown dengan Widdershins.
  3. Mengekspor dokumentasi langsung dari proyek aktif dengan Apidog CLI.

Untuk konteks tambahan, lihat daftar alat dokumentasi API REST teratas dan alat dokumentasi API gratis.

Siapkan file OpenAPI 3.x, misalnya openapi.yaml atau openapi.json. Sebagian besar perintah berikut menerima kedua format tersebut.

Buat referensi HTML dengan Redocly CLI

Redocly CLI mengubah deskripsi OpenAPI menjadi satu file HTML mandiri. File hasilnya berisi konten, gaya, dan skrip sehingga dapat langsung di-host atau dibagikan.

1. Instal CLI

Instal secara global:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

Atau gunakan npx jika Anda tidak ingin instalasi global.

2. Bangun dokumentasi dari spesifikasi 

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Secara default, Redocly membuat file redoc-static.html di direktori saat ini.

3. Tentukan lokasi output

Gunakan --output untuk menentukan nama atau lokasi file:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Buka docs/index.html di browser untuk melihat referensi API tiga panel.

Redocly CLI mendukung Swagger 2.0 serta OpenAPI 3.0/3.1. Namun, build-docs berfokus pada halaman referensi API; panduan onboarding, tutorial, dan halaman dokumentasi lain perlu dikelola secara terpisah.

Hasilkan Markdown dengan Widdershins

Jika dokumentasi Anda dibangun dari Markdown—misalnya untuk static site generator atau folder docs/ di repository—gunakan Widdershins. Tool ini mengonversi OpenAPI, Swagger, atau AsyncAPI ke Markdown yang kompatibel dengan Slate.

1. Instal Widdershins 

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

2. Konversi spesifikasi ke Markdown 

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

File api.md dapat langsung di-commit ke repository atau diproses oleh generator situs dokumentasi Anda.

3. Tambahkan contoh kode per bahasa

Gunakan --language_tabs untuk menyertakan tab contoh kode:

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

Jika Anda tidak menggunakan -o, output akan ditulis ke stdout. Ini berguna untuk pipeline shell:

widdershins openapi.yaml | tee docs/api.md
Enter fullscreen mode Exit fullscreen mode

Widdershins cocok untuk workflow berbasis Markdown. Untuk alur yang lebih luas, lihat panduan tentang generator dokumen API dengan ekspor Markdown.

Perlu diingat: Redocly dan Widdershins membaca file statis. Jika openapi.yaml tidak sinkron dengan definisi API yang sedang diedit tim, dokumentasi yang dihasilkan juga akan tertinggal.

Dokumentasi dari proyek yang sedang berjalan dengan Apidog CLI

Apidog CLI menyediakan jalur terintegrasi untuk mengekspor dokumentasi dari proyek yang sedang aktif. Endpoint, skema, dan dokumen tertulis berada dalam satu proyek, lalu CLI mengekspor data dari sumber yang sama.

1. Instal dan autentikasi 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Untuk penyiapan awal, lihat panduan instalasi Apidog CLI.

Autentikasi menggunakan personal access token:

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Token disimpan pada mesin yang menjalankan perintah. Setelah login, perintah berikut menggunakan ID proyek.

Gunakan --help pada setiap perintah untuk memeriksa flag yang tersedia di versi CLI Anda.

Impor spesifikasi ke dalam proyek

Jika API Anda sudah tersedia sebagai file OpenAPI, impor file tersebut ke proyek Apidog:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import menerima OpenAPI 3.x, Swagger 2.0, Postman, dan format Apidog. Setelah diimpor, proyek menjadi sumber yang dapat diekspor kembali oleh CLI.

Ekspor dokumentasi yang mudah dibaca

Gunakan apidog export untuk menghasilkan OpenAPI, HTML, Markdown, atau Postman. Periksa bantuan perintah terlebih dahulu:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Ekspor ke Markdown 

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

Ekspor ke HTML 

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

Ekspor kembali ke OpenAPI 

apidog export \
  --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Jika satu proyek berisi beberapa layanan, periksa apidog export --help untuk flag pembatasan cakupan dan ID layanan yang tersedia pada versi CLI Anda.

Kelola panduan tertulis, bukan hanya referensi

Referensi endpoint saja tidak cukup. Dokumentasi API biasanya juga memerlukan panduan memulai, autentikasi, migrasi, dan contoh integrasi.

Di Apidog, dokumen tersebut berada dalam pohon dokumentasi proyek sebagai Markdown. Gunakan grup perintah doc untuk mengelolanya:

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

Alur kerja yang disarankan:

  1. Jalankan perintah terhadap proyek.
  2. Baca hasil JSON.
  3. Ikuti agentHints.nextSteps yang dikembalikan CLI.
  4. Validasi payload JSON sebelum mengirim perubahan.

Periksa skema dan subcommand validasi yang tersedia:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

Validasi lokal membantu mendeteksi field yang hilang sebelum request dikirim.

Publikasikan situs dokumentasi

Setelah referensi dan panduan siap, kelola publikasi dari terminal:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

Perbedaan perintahnya:

  • doc: mengelola dokumen Markdown di dalam pohon API proyek.
  • docs-site: mengelola situs dokumentasi publik yang di-hosting.
  • shared-doc: mengelola tautan dokumentasi yang dapat dibagikan.

Gunakan docs-site untuk mengelola situs publik melalui CLI. Gunakan shared-doc ketika Anda hanya perlu membagikan dokumentasi kepada mitra atau pengguna tertentu.

Integrasikan ke CI

Setelah perintah berjalan secara lokal, masukkan ke pipeline CI. Contoh GitHub Actions berikut meregenerasi dokumentasi Markdown:

- 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
Enter fullscreen mode Exit fullscreen mode

Simpan token sebagai GitHub Secret, bukan di file workflow.

Untuk workflow berbasis file statis, gunakan bentuk yang sama dengan Redocly atau Widdershins:

- name: Build HTML API docs
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Dengan pola ini, dokumentasi menjadi artefak build yang dapat diregenerasi setiap ada perubahan.

Untuk referensi perintah lebih lengkap, lihat panduan lengkap Apidog CLI.

Masalah umum

ID proyek salah atau tidak ada

Perintah Apidog seperti export, doc, dan docs-site memerlukan:

--project <projectId>
Enter fullscreen mode Exit fullscreen mode

Gunakan ID proyek dari pengaturan proyek, bukan nama proyek yang mudah dibaca.

Token tidak tersedia di CI

apidog login menyimpan token pada mesin yang menjalankannya. CI runner baru tidak memiliki token tersimpan, jadi jalankan login di job yang sama sebelum ekspor:

apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

File OpenAPI sudah usang

Redocly dan Widdershins selalu membaca file yang Anda berikan. Jika openapi.yaml lama, hasil dokumentasinya juga lama. Pastikan file spesifikasi diperbarui sebelum build, atau ekspor langsung dari proyek aktif.

Menebak flag CLI

Flag untuk export, doc, docs-site, dan shared-doc dapat berbeda antarversi CLI. Jangan menebak—periksa bantuan:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

Kesimpulan

Pilih tool berdasarkan output dan sumber data yang Anda butuhkan:

  • Gunakan Redocly CLI untuk referensi HTML mandiri.
  • Gunakan Widdershins untuk dokumentasi Markdown.
  • Gunakan Apidog CLI saat Anda ingin mengekspor referensi, panduan tertulis, dan dokumentasi yang dipublikasikan dari satu proyek aktif.

Apa pun tool yang dipilih, jalankan generator dokumentasi di CI. Dengan begitu, dokumentasi diperbarui bersama perubahan API, bukan sebagai tugas manual setelahnya.

Unduh Apidog untuk mencoba workflow CLI pada proyek Anda, atau pelajari bagaimana Apidog dapat digunakan dalam workflow yang mengutamakan API.

Top comments (0)