Cara Membuat Dokumentasi API Otomatis dengan Agen AI Menggunakan Apidog CLI

Dokumentasi API adalah tugas yang disetujui semua orang penting dan tidak ada yang ingin memilikinya. Sebuah endpoint baru dirilis, referensi tertinggal seminggu, dan panduan memulai menggambarkan alur otentikasi yang Anda ganti dua sprint lalu. Pekerjaan ini nyata, tetapi berulang dan mudah ditunda.

Kombinasi tersebut (penting, berulang, bisa ditunda) adalah persis apa yang dikuasai agen AI. Jika agen Anda dapat menjalankan perintah terminal, ia dapat membuat endpoint, menulis panduan naratif di sekitarnya, dan menerbitkan situs dokumentasi, semuanya dari permintaan bahasa alami. CLI Apidog-lah yang memungkinkan hal itu: setiap tindakan dokumentasi adalah perintah yang dapat diskrip dengan output JSON terstruktur yang dapat dibaca dan ditindaklanjuti oleh agen.

Mengapa CLI, bukan GUI atau server MCP

Ada tiga cara agen dapat mengakses dokumen API Anda, dan semuanya memecahkan masalah yang berbeda. Memahami perbedaan ini dengan benar adalah perbedaan antara berjuang dengan alat Anda dan menggunakan yang dibuat untuk pekerjaan itu.

Sebuah server MCP sangat baik ketika Anda ingin agen untuk membaca definisi API Anda dan menghasilkan kode klien berdasarkan itu. Alur doc-through-MCP Cursor adalah contoh kanonis. Tapi itu kebalikan dari apa yang kita inginkan di sini. Kita ingin agen untuk memproduksi dokumentasi: membuat endpoint, menulis panduan Markdown, dan menerbitkan situs.

Untuk itu, CLI unggul dalam tiga hal. Ia deterministik: perintah yang sama menghasilkan hasil yang sama. Ia dapat diskrip: seluruh alur dapat diintegrasikan ke CI. Dan ia mengembalikan JSON pada setiap panggilan, termasuk bidang agentHints.nextSteps yang memberi tahu agen apa yang dapat dilakukannya selanjutnya. Poin terakhir itu lebih penting dari kedengarannya: itu berarti agen tidak menebak-nebak jalannya, ia mengikuti saran CLI sendiri.

Menyiapkan lingkungan agen

Instal CLI dan otentikasi sekali. Panduan instalasi kami mencakup versi Node dan PATH; panduan otentikasi mencakup token dan rahasia CI.

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

Ambil token dari aplikasi Apidog di bawah avatar pengguna → Pengaturan Akun → Token Akses API. Token disimpan secara lokal setelah login, jadi agen tidak meneruskannya di setiap panggilan.

Setiap penulisan berjalan terhadap ID proyek, yang dapat Anda temukan di Pengaturan Proyek → Pengaturan Dasar, atau dengan menjalankan:

apidog project list

Agen pengkodean apa pun yang dapat menjalankan perintah shell berfungsi di sini: Claude Code, Cursor, Codex, dan lainnya. CLI tidak peduli siapa yang memanggilnya; ia hanya peduli bahwa perintah dan payload sudah benar. Ini membawa kita pada satu aturan yang membuat semuanya dapat diandalkan.

Ritual penulisan yang harus diikuti agen

Perintah dokumentasi yang membuat sumber daya membutuhkan file JSON. Agen Anda tidak boleh membuat JSON tersebut secara manual dari memori. Nama bidang yang dibuat oleh model adalah penyebab utama kegagalan eksekusi. CLI menyediakan skema yang tepat untuk setiap penulisan, dan urutan yang benar selalu sama dalam empat langkah:

# 1. Ask the CLI what the payload looks like
apidog cli-schema get doc-create

# 2. Generate the JSON file from that schema

# 3. Validate before you write (catches a missing field locally)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Only now run the real command
apidog doc create --project <projectId> --file ./doc.json

Sematkan alur ini ke dalam instruksi agen. Ini mengubah "model membuat bidang" menjadi "validator menolaknya di mesin saya," yang merupakan perbedaan antara eksekusi bersih dan build gagal. Berikut adalah blok aturan yang dapat Anda tempelkan langsung ke prompt sistem agen atau file CLAUDE.md / .cursorrules:

Apidog CLI rules:
- Never hand-write a JSON payload. Run `apidog cli-schema get <key>` first and build from that schema.
- Validate every file with `apidog cli-schema validate <key> --file <path>` before any create or update.
- Always pass --project <id> on write commands.
- Read the `agentHints.nextSteps` field in each JSON response to choose the next command.
- If a write comes back blocked by permissions, stop and ask the human; do not pick a workaround.

Lima baris tersebutlah yang membedakan agen yang secara andal mengirimkan dokumen dari agen yang menebak payload ke dinding.

Langkah 1: Buat referensi dari endpoint dan skema

Di Apidog, referensi API Anda dibuat dari endpoint dan skema data dalam proyek. Jadi, tugas pertama agen adalah membuat itu. Misalkan Anda memberitahunya:

“Tambahkan endpoint POST /refunds yang menerima ID pesanan dan jumlah, dan dokumentasikan respons keberhasilan serta respons kesalahan validasinya.”

Agen membuat model data yang dapat digunakan kembali terlebih dahulu, kemudian endpoint yang mereferensikannya. Menjalankan apidog cli-schema get schema-create menunjukkan bahwa skema data memerlukan name dan objek jsonSchema standar. Jadi agen menulis sesuatu seperti 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" }
    }
  }
}

Validasi dan buat:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Sekarang endpoint. Skema endpoint-create memerlukan method dan path, dan memungkinkan Anda mereferensikan model data yang baru saja Anda buat dengan $ref dalam format #/definitions/{schemaId}. Agen menulis refunds-endpoint.json:

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

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

Dokumentasi referensi untuk /refunds sekarang ada, dirender dari definisi yang sama yang diedit tim Anda. Tidak ada langkah "ekspor dokumen" terpisah untuk referensi; ia langsung aktif di proyek saat endpoint dibuat. Itulah keuntungan dari sumber yang berorientasi skema: referensi tidak dapat melenceng, karena ia adalah skema.

Langkah 2: Tulis panduan, bukan hanya referensi

Referensi yang dibuat dari skema hanyalah separuh dari dokumentasi yang baik. Separuh lainnya adalah narasi: halaman memulai, panduan otentikasi, catatan migrasi. Di Apidog, hal-hal tersebut tersimpan dalam pohon dokumen proyek sebagai dokumen Markdown, dikelola oleh grup perintah doc.

Skema doc-create hanya memerlukan name; content menampung Markdown, dan folderId menempatkannya di pohon (0 adalah root). Jadi, quickstart yang dibuat agen menjadi 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
}

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

Di sinilah agen menunjukkan kemampuannya. Mintalah agen untuk "menulis panduan cepat yang memandu developer baru dari kunci API hingga pengembalian dana pertama," dan agen akan membuat draf Markdown, membungkusnya dalam payload yang diharapkan skema, memvalidasi, dan membuat dokumen. Tanpa browser, tanpa salin-tempel. Karena konten hanyalah bidang string, agen dapat menulis panduan sepanjang atau sedetail yang diminta tugas.

Langkah 3: Publikasikan situs dokumen

Dengan referensi dan panduan yang sudah ada, agen juga dapat memublikasikan dari terminal. Dua grup perintah menangani ini, dan satu perbedaan penamaan sering membingungkan orang:

• doc: dokumen Markdown di dalam pohon API proyek (apa yang Anda buat di langkah 2).
• docs-site: situs dokumentasi publik yang di-hosting.
• shared-doc: tautan yang dapat dibagikan untuk diberikan kepada mitra, bukan situs lengkap.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Gunakan docs-site ketika Anda ingin situs publik yang didefinisikan dari terminal, dan shared-doc ketika Anda hanya perlu tautan untuk dikirim kepada seseorang. Karena keduanya adalah perintah, penerbitan menjadi langkah yang diskrip yang dijalankan agen setelah setiap perubahan dokumen; situs yang di-hosting mencerminkan pembaruan saat perintah kembali.

Langkah 4 (opsional): Ekspor salinan portabel

Terkadang Anda menginginkan dokumen sebagai file: halaman HTML untuk di-hosting di tempat lain, Markdown untuk generator situs statis, atau OpenAPI untuk diberikan kepada pihak downstream. Perintah export menghasilkan ketiganya:

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

Jika proyek Anda memiliki beberapa layanan dan Anda hanya ingin mendokumentasikan sebagian darinya, apidog export --help menunjukkan flag --scope, --api-ids, dan --folder-ids untuk mempersempit output. Satu proyek dapat mengirimkan satu file dokumen per layanan dengan cara itu.

Contoh lengkap, ujung ke ujung

Berikut adalah seluruh alur sebagai satu permintaan bahasa alami dan perintah yang dijalankan agen untuk memenuhinya.

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

Agen, mengikuti aturannya, menjalankan:

# Create the shared data model
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Create both endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Author the idempotency guide as a Markdown doc
apidog doc create --project $PID --file ./idempotency-guide.json

# Publish
apidog docs-site create --project $PID --file ./docs-site.json

Anda meninjau perbedaan yang dihasilkan, dan layanan pembayaran didokumentasikan serta aktif. Apa yang dulu merupakan sore hari untuk beralih konteks kini menjadi permintaan dan ulasan.

Hubungkan ke alur agen atau CI

Karena setiap langkah adalah perintah, seluruh alur dapat diintegrasikan ke CI atau alur tugas agen. Langkah minimal yang meregenerasi dan mengkomit referensi Markdown Anda 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

Untuk gambaran yang lebih lengkap tentang menjalankan agen terhadap CLI secara end-to-end, lihat Dari PRD hingga Alur Pengujian dan Cara Menyiapkan 5 Agen AI untuk Membangun API Lengkap. Polanya sama di keduanya: jelaskan maksud, biarkan agen menerjemahkannya ke panggilan CLI yang divalidasi, tinjau hasilnya.

Satu catatan izin

Penulisan ke proyek melalui agen dapat dibatasi. Jika perintah create kembali terblokir, proyek tersebut memiliki Izin Edit AI Eksternal yang dinonaktifkan untuk cabang tersebut. Anda memiliki dua pilihan jujur: aktifkan izin edit langsung di Pengaturan Proyek → Pengaturan Fitur → Pengaturan Fitur AI (klien Apidog 2.8.32+), atau minta agen bekerja pada cabang AI yang terisolasi dan buka permintaan penggabungan. Panduan pendamping tentang memperbarui spesifikasi API Anda menjelaskan alur cabang AI secara lengkap, dan berlaku sama ketika agen membuat dokumentasi pada cabang yang dilindungi.

Masalah umum

Agen membuat JSON secara manual. Ini adalah kegagalan nomor satu. Terapkan cli-schema get → cli-schema validate → create dalam instruksi agen agar ia bekerja dari skema yang sebenarnya, bukan yang ditebak.

ID proyek hilang. Setiap panggilan doc, docs-site, dan export memerlukan --project <projectId>, ID dari pengaturan, bukan nama proyek yang dapat dibaca. Sebagian besar laporan "terjadi kesalahan" adalah karena ini.

Membingungkan doc, docs-site, dan shared-doc. Ketiganya adalah hal yang berbeda: halaman Markdown di pohon, situs yang di-hosting, dan tautan berbagi. Minta agen untuk mengkonfirmasi mana yang dimaksud tugas sebelum ia menulis.

Token tidak diatur di CI. apidog login menyimpan token di mesin yang menjalankannya. Runner CI yang baru tidak memilikinya, jadi jalankan login --with-token di job yang sama sebelum perintah apa pun, dan simpan token dalam rahasia.

$ref yang tidak menunjuk ke mana-mana. Ketika sebuah endpoint mereferensikan model data dengan #/definitions/{schemaId}, skema tersebut harus ada terlebih dahulu. Buat skema sebelum endpoint yang menggunakannya.

FAQ

Agen AI mana yang dapat menggerakkan Apidog CLI? Agen apa pun yang dapat menjalankan perintah shell: Claude Code, Cursor, Codex, dan agen pengkodean serupa. CLI tidak bergantung pada agen; ia hanya membutuhkan perintah yang benar dan payload yang valid.

Apakah saya memerlukan paket berbayar? Tidak. Apidog bukan open source, tetapi tingkat gratis ditambah apidog-cli mencakup alur pembuatan dan publikasi yang dijelaskan di sini.

Bisakah agen secara tidak sengaja menimpa dokumen yang ada? create menambahkan sumber daya baru. Memodifikasi yang sudah ada menggunakan update, yang berperilaku berbeda dan membutuhkan perlindungan tersendiri; itu tercakup dalam panduan pendamping memperbarui spesifikasi API Anda.

Apa bedanya ini dengan generator dokumen AI? Alat dokumen AI generik menghasilkan teks dari kode Anda. Ini menghasilkan dokumentasi terstruktur di dalam platform API Anda (endpoint, skema, panduan, dan situs yang dipublikasikan) dari satu sumber langsung yang tidak dapat menyimpang dari apa yang diedit tim Anda.

Kesimpulan

Agen yang dapat menjalankan Apidog CLI dapat mengambil alih bagian dokumentasi yang selalu ditunda orang: ia membuat endpoint, menulis panduan di sekitarnya, dan mempublikasikan situs. Semua dari permintaan bahasa alami, dengan validasi skema menjaga setiap penulisan. Peran Anda bergeser dari menulis dokumen menjadi meninjau perbedaan.

Satu aturan yang membuatnya dapat diandalkan adalah ritual penulisan: dapatkan skema, validasi, lalu buat. Beri agen Anda alur itu, blok aturan lima baris di atas, dan ID proyek, dan dokumentasi berhenti menjadi pekerjaan rumah yang tertinggal di belakang kode. Unduh Apidog untuk mendapatkan CLI, atau baca panduan lengkap Apidog CLI untuk referensi perintah lengkap.