DEV Community

Cover image for Cara Membuat Dokumentasi API Otomatis dengan Agen AI Menggunakan Apidog CLI
Walse
Walse

Posted on • Originally published at apidog.com

Cara Membuat Dokumentasi API Otomatis dengan Agen AI Menggunakan Apidog CLI

Dokumentasi API adalah pekerjaan penting yang sering tertunda: endpoint baru dirilis, referensi tertinggal, dan panduan memulai masih menjelaskan alur autentikasi lama. Karena tugas ini berulang dan mudah ditunda, dokumentasi adalah kandidat kuat untuk otomatisasi oleh agen AI.

Coba Apidog hari ini

Jika agen dapat menjalankan perintah terminal, agen dapat membuat endpoint, menulis panduan Markdown, lalu menerbitkan situs dokumentasi dari instruksi bahasa alami. Apidog CLI memungkinkan alur ini melalui perintah yang dapat diskrip dan output JSON terstruktur yang dapat dibaca agen.

Mengapa CLI, bukan GUI atau server MCP?

Ada tiga pendekatan untuk memberi agen akses ke dokumentasi API. Masing-masing menyelesaikan masalah yang berbeda.

Pendekatan Arah Penggerak Perubahan dapat ditinjau?
GUI Mengedit di browser Manusia yang mengklik Tidak
Server MCP Membaca spesifikasi API → menulis kode Agen di editor Ya, tetapi di repo kode
CLI Menulis dokumentasi Agen di terminal Ya, setiap perintah tercatat

Server MCP cocok ketika Anda ingin agen membaca spesifikasi API dan menghasilkan kode klien. Alur dokumentasi melalui MCP di Cursor adalah contoh penggunaan tersebut.

Namun, jika tujuan Anda adalah memproduksi dokumentasi—membuat endpoint, menulis panduan, dan menerbitkan situs—CLI lebih sesuai.

Apidog CLI memberikan tiga keuntungan utama:

  1. Deterministik: perintah yang sama menghasilkan output yang sama.
  2. Dapat diskrip: alur dapat dijalankan dari CI atau agen.
  3. Berbasis JSON: setiap respons dapat menyertakan agentHints.nextSteps, sehingga agen dapat memilih perintah berikutnya berdasarkan respons CLI, bukan menebak.

Menyiapkan lingkungan agen

Instal Apidog CLI dan lakukan autentikasi sekali.

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Tampilan instalasi Apidog CLI

Ambil token dari aplikasi Apidog melalui avatar pengguna → Pengaturan Akun → Token Akses API. Setelah login, token disimpan secara lokal sehingga agen tidak perlu meneruskannya pada setiap perintah.

Lokasi Token Akses API di Apidog

Setiap operasi tulis membutuhkan ID proyek. Anda dapat menemukannya melalui Pengaturan Proyek → Pengaturan Dasar, atau dari terminal:

apidog project list
Enter fullscreen mode Exit fullscreen mode

Agen pengkodean apa pun yang dapat menjalankan shell dapat menggunakan alur ini, termasuk Claude Code, Cursor, Codex, dan agen serupa.

Contoh penggunaan CLI dengan agen

Contoh konfigurasi agen

Ritual penulisan yang harus diikuti agen

Jangan biarkan agen menulis payload JSON dari ingatan. Nama field yang ditebak model adalah salah satu penyebab utama kegagalan eksekusi.

Untuk setiap operasi create atau update, gunakan urutan berikut:

# 1. Ambil skema payload dari CLI
apidog cli-schema get doc-create

# 2. Buat file JSON berdasarkan skema tersebut

# 3. Validasi payload secara lokal
apidog cli-schema validate doc-create --file ./doc.json

# 4. Jalankan perintah tulis hanya setelah validasi berhasil
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

Tempelkan aturan berikut ke prompt sistem agen, CLAUDE.md, atau .cursorrules:

Aturan Apidog CLI:
- Jangan pernah menulis payload JSON secara manual. Jalankan `apidog cli-schema get <key>` terlebih dahulu.
- Validasi setiap file dengan `apidog cli-schema validate <key> --file <path>` sebelum create atau update.
- Selalu sertakan --project <id> pada perintah tulis.
- Baca `agentHints.nextSteps` dalam setiap respons JSON untuk menentukan perintah berikutnya.
- Jika operasi tulis diblokir oleh izin, berhenti dan minta keputusan manusia. Jangan mencari jalan pintas.
Enter fullscreen mode Exit fullscreen mode

Dengan alur ini, kesalahan berpindah dari “payload gagal saat dikirim” menjadi “validator menolak payload secara lokal”.

Langkah 1: Buat referensi dari endpoint dan skema

Referensi API di Apidog dibangun dari endpoint dan skema data proyek. Jadi, mulai dengan model data yang dapat digunakan ulang.

Misalnya, Anda memberi instruksi berikut kepada agen:

“Tambahkan endpoint POST /refunds yang menerima ID pesanan dan jumlah, lalu dokumentasikan respons berhasil dan respons kesalahan validasi.”

Pertama, ambil skema untuk membuat model data:

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

Buat file refund-schema.json:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Validasi lalu buat skema:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

Selanjutnya, ambil skema untuk endpoint:

apidog cli-schema get endpoint-create
Enter fullscreen mode Exit fullscreen mode

Buat refunds-endpoint.json. Endpoint dapat mereferensikan model data yang baru dibuat melalui $ref dengan format #/definitions/{schemaId}.

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": {
      "$ref": "#/definitions/<refundSchemaId>"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Validasi lalu buat endpoint:

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Enter fullscreen mode Exit fullscreen mode

Referensi untuk /refunds kini tersedia langsung di proyek. Tidak ada langkah ekspor terpisah untuk membuat referensi, karena referensi dirender dari definisi endpoint dan skema yang sama.

Langkah 2: Tulis panduan, bukan hanya referensi

Referensi endpoint tidak cukup untuk onboarding developer. Anda juga membutuhkan panduan memulai, autentikasi, migrasi, dan penjelasan alur bisnis.

Di Apidog, panduan tersebut disimpan sebagai dokumen Markdown di pohon dokumen proyek dan dikelola melalui grup perintah doc.

Ambil skema dokumen:

apidog cli-schema get doc-create
Enter fullscreen mode Exit fullscreen mode

Buat quickstart.json:

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}
Enter fullscreen mode Exit fullscreen mode

Nilai folderId: 0 menempatkan dokumen di root.

Sebelum membuat dokumen, lihat struktur dokumen yang ada dan validasi payload:

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Enter fullscreen mode Exit fullscreen mode

Contoh instruksi yang dapat diberikan ke agen:

“Tulis panduan cepat untuk developer baru, mulai dari mendapatkan API key hingga membuat pengembalian dana pertama.”

Agen dapat menyusun Markdown, memasukkannya ke payload yang sesuai skema, memvalidasi file, lalu membuat dokumen tanpa membuka browser atau melakukan salin-tempel.

Langkah 3: Publikasikan situs dokumentasi

Setelah referensi dan panduan tersedia, publikasikan dokumentasi dari terminal.

Bedakan tiga grup perintah berikut:

  • doc: dokumen Markdown di dalam pohon dokumentasi proyek.
  • docs-site: situs dokumentasi publik yang di-hosting.
  • shared-doc: tautan berbagi untuk mitra atau pihak tertentu.

Mulai dengan melihat situs dokumentasi yang tersedia:

apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Lalu ambil skema dan buat situs:

apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Gunakan docs-site untuk situs publik yang dikelola dari terminal. Gunakan shared-doc jika Anda hanya membutuhkan tautan berbagi.

Karena semua langkah adalah perintah CLI, agen dapat menjalankan publikasi setelah perubahan dokumentasi selesai.

Langkah 4: Ekspor salinan portabel

Jika Anda membutuhkan dokumentasi sebagai file—misalnya untuk static site generator, hosting lain, atau integrasi downstream—gunakan export.

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Untuk proyek dengan beberapa layanan, gunakan bantuan perintah untuk melihat opsi penyaringan:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Gunakan flag berikut untuk mempersempit output:

  • --scope
  • --api-ids
  • --folder-ids

Dengan demikian, satu proyek dapat mengekspor dokumentasi terpisah untuk setiap layanan.

Contoh lengkap, ujung ke ujung

Berikut contoh instruksi bahasa alami:

Anda: “Kami baru saja menambahkan layanan pembayaran dengan POST /refunds dan GET /refunds/{id}. Dokumentasikan keduanya, tulis panduan singkat tentang kunci idempoten, dan publikasikan ke situs dokumentasi kami.”

Agen menjalankan alur berikut:

# Buat model data bersama
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Buat kedua endpoint
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Buat panduan idempotensi sebagai dokumen Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# Publikasikan situs dokumentasi
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Setelah itu, Anda cukup meninjau perubahan yang dibuat. Endpoint, panduan, dan situs dokumentasi telah diperbarui melalui satu alur yang dapat diaudit.

Hubungkan ke alur agen atau CI

Karena setiap tahap dapat dijalankan dari shell, Anda dapat memasukkannya ke pipeline CI.

Contoh job minimum untuk meregenerasi dan menyimpan referensi Markdown pada setiap push:

- 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

Untuk contoh alur agen yang lebih lengkap, baca Dari PRD hingga Alur Pengujian dan Cara Menyiapkan 5 Agen AI untuk Membangun API Lengkap.

Polanya sama:

  1. Jelaskan maksud perubahan.
  2. Biarkan agen menerjemahkannya menjadi perintah CLI tervalidasi.
  3. Tinjau hasilnya.

Catatan tentang izin

Operasi tulis oleh agen dapat dibatasi oleh konfigurasi proyek.

Jika perintah create diblokir, kemungkinan Izin Edit AI Eksternal dinonaktifkan untuk cabang tersebut. Pilihan yang tersedia:

  1. Aktifkan izin edit melalui Pengaturan Proyek → Pengaturan Fitur → Pengaturan Fitur AI pada klien Apidog 2.8.32+.
  2. Minta agen bekerja pada cabang AI yang terisolasi, lalu buka permintaan penggabungan.

Panduan memperbarui spesifikasi API dengan agen menjelaskan alur cabang AI ini secara lebih lengkap. Pola yang sama juga berlaku saat agen membuat dokumentasi pada cabang yang dilindungi.

Masalah umum

Agen menulis JSON secara manual

Ini adalah kegagalan paling umum. Terapkan urutan berikut dalam instruksi agen:

cli-schema get → cli-schema validate → create
Enter fullscreen mode Exit fullscreen mode

Dengan begitu, agen menggunakan skema aktual dari CLI, bukan field yang ditebak.

ID proyek tidak disertakan

Setiap perintah doc, docs-site, dan export membutuhkan:

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

Gunakan ID proyek, bukan nama proyek yang dapat dibaca manusia.

Keliru membedakan doc, docs-site, dan shared-doc

Ketiganya berbeda:

  • doc: halaman Markdown di pohon dokumentasi.
  • docs-site: situs dokumentasi yang di-hosting.
  • shared-doc: tautan berbagi.

Pastikan agen mengonfirmasi target sebelum membuat sumber daya.

Token tidak tersedia di CI

apidog login menyimpan token pada mesin yang menjalankannya. Runner CI baru tidak memiliki token tersebut, jadi lakukan login di job yang sama:

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

Simpan token sebagai secret CI.

$ref tidak menunjuk ke skema yang valid

Jika endpoint menggunakan:

{
  "$ref": "#/definitions/<schemaId>"
}
Enter fullscreen mode Exit fullscreen mode

Skema tersebut harus dibuat terlebih dahulu. Buat model data sebelum endpoint yang mereferensikannya.

FAQ

Agen AI apa yang dapat menjalankan Apidog CLI?

Agen apa pun yang dapat menjalankan shell, seperti Claude Code, Cursor, Codex, dan agen pengkodean serupa. CLI tidak bergantung pada agen tertentu; yang penting adalah perintah dan payload valid.

Apakah saya memerlukan paket berbayar?

Tidak. Apidog bukan open source, tetapi tingkat gratis bersama apidog-cli mencakup alur pembuatan dan publikasi yang dijelaskan di sini.

Bisakah agen menimpa dokumen yang sudah ada?

Perintah create menambahkan sumber daya baru. Untuk mengubah sumber daya yang ada, gunakan update, yang memiliki perilaku dan perlindungan berbeda. Lihat panduan pembaruan spesifikasi API untuk detailnya.

Apa bedanya dengan generator dokumentasi AI biasa?

Generator dokumentasi AI generik menghasilkan teks dari kode. Alur ini membuat dokumentasi terstruktur di platform API Anda: endpoint, skema, panduan, dan situs yang dipublikasikan. Semua tetap berasal dari sumber yang sama dengan definisi yang dikelola tim.

Kesimpulan

Agen yang dapat menjalankan Apidog CLI dapat mengambil alih pekerjaan dokumentasi yang sering tertunda: membuat endpoint, menulis panduan, dan menerbitkan situs dokumentasi dari instruksi bahasa alami.

Kunci keandalannya adalah ritual penulisan:

Ambil skema → validasi payload → jalankan create atau update
Enter fullscreen mode Exit fullscreen mode

Berikan agen aturan tersebut, ID proyek, dan akses yang sesuai. Setelah itu, peran Anda bergeser dari menulis dokumentasi secara manual menjadi meninjau perubahan yang dapat dilacak.

Unduh Apidog untuk mendapatkan CLI, atau baca panduan lengkap Apidog CLI untuk referensi perintah lengkap.

Top comments (0)