วิธีให้ AI Agent สร้างเอกสาร API ด้วย Apidog CLI

การจัดทำเอกสาร API เป็นงานที่ทุกคนเห็นพ้องต้องกันว่าสำคัญ แต่ไม่มีใครอยากรับผิดชอบ เมื่อมีการปล่อย endpoint ใหม่ เอกสารอ้างอิงก็จะตามหลังไปหนึ่งสัปดาห์ และคู่มือเริ่มต้นใช้งานก็อธิบายขั้นตอนการยืนยันตัวตนที่คุณเปลี่ยนไปเมื่อสองสปริงที่แล้ว งานนี้มีอยู่จริง แต่ก็เป็นงานซ้ำซากที่ง่ายต่อการเลื่อนออกไป

การผสมผสานลักษณะเหล่านี้ (สำคัญ ซ้ำซาก เลื่อนออกไปได้) คือสิ่งที่ AI agent เก่งเป็นพิเศษ หาก agent ของคุณสามารถรันคำสั่งใน terminal ได้ มันก็สามารถสร้าง endpoints, เขียนคู่มือประกอบ, และเผยแพร่เว็บไซต์เอกสารได้ทั้งหมดจากคำขอที่เป็นภาษามนุษย์ทั่วไป Apidog CLI คือสิ่งที่ทำให้สิ่งนี้เป็นไปได้: ทุกการกระทำเกี่ยวกับการจัดทำเอกสารเป็นคำสั่งที่สามารถเขียนสคริปต์ได้ พร้อมด้วยเอาต์พุต JSON ที่มีโครงสร้างซึ่ง agent สามารถอ่านและดำเนินการต่อได้

button

ทำไมต้องใช้ CLI ไม่ใช่ GUI หรือ MCP server

มีสามวิธีที่ agent สามารถจัดการเอกสาร API ของคุณได้ ซึ่งแต่ละวิธีแก้ปัญหาที่แตกต่างกัน การทำความเข้าใจความแตกต่างนี้อย่างถูกต้องคือความแตกต่างระหว่างการต่อสู้กับเครื่องมือของคุณกับการใช้เครื่องมือที่สร้างมาเพื่องานนั้น

แนวทาง	ทิศทาง	ใครเป็นผู้ขับเคลื่อน	Diff ที่ตรวจสอบได้?
GUI	มนุษย์แก้ไขในเบราว์เซอร์	บุคคล, คลิก	ไม่
MCP server	อ่านสเปกของคุณ → เขียนโค้ด	Agent, ใน editor ของคุณ	ใน repo โค้ดของคุณ ไม่ใช่เอกสาร
CLI	เขียนเอกสารเอง	Agent, ใน terminal	ใช่, ทุกคำสั่งถูกบันทึก

MCP server นั้นยอดเยี่ยมเมื่อคุณต้องการให้ agent อ่านคำจำกัดความ API ของคุณและสร้างโค้ดไคลเอ็นต์จากมัน ขั้นตอนการจัดทำเอกสารผ่าน MCP ของ Cursor เป็นตัวอย่างที่เป็นแบบอย่าง แต่สิ่งนั้นตรงกันข้ามกับสิ่งที่เราต้องการที่นี่ เราต้องการให้ agent สร้างเอกสาร: สร้าง endpoints, เขียนคู่มือ Markdown และเผยแพร่เว็บไซต์

สำหรับสิ่งนั้น CLI เหนือกว่าในสามประการ มันเป็นแบบกำหนดได้: คำสั่งเดียวกันให้ผลลัพธ์เดียวกัน มันสามารถเขียนสคริปต์ได้: กระบวนการทั้งหมดสามารถรวมเข้ากับ CI ได้ และมันส่งคืน JSON ในทุกการเรียกใช้ รวมถึงฟิลด์ agentHints.nextSteps ที่บอก agent ว่าจะทำอะไรต่อไปได้ ประเด็นสุดท้ายนี้สำคัญกว่าที่คิด: มันหมายความว่า agent ไม่ได้คาดเดาไปข้างหน้า แต่กำลังทำตามคำแนะนำของ CLI เอง

ตั้งค่าสภาพแวดล้อมของ Agent

ติดตั้ง CLI และยืนยันตัวตนเพียงครั้งเดียว คู่มือการติดตั้งของเราครอบคลุมเวอร์ชัน Node และ PATH; คู่มือการยืนยันตัวตนครอบคลุมโทเค็นและ CI secrets

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

รับโทเค็นจากแอป Apidog ใต้รูปโปรไฟล์ผู้ใช้ → การตั้งค่าบัญชี → API Access Token โทเค็นจะถูกเก็บไว้ในเครื่องหลังจากเข้าสู่ระบบ ดังนั้น agent ไม่จำเป็นต้องส่งโทเค็นไปทุกครั้งที่เรียกใช้

ทุกการเขียนจะดำเนินการกับ project ID ซึ่งคุณจะพบได้ในการตั้งค่าโปรเจกต์ → การตั้งค่าพื้นฐาน หรือโดยการรัน:

apidog project list

Coding agent ใด ๆ ที่สามารถรันคำสั่ง shell ได้ก็ใช้ได้ที่นี่: Claude Code, Cursor, Codex และอื่น ๆ CLI ไม่สนใจว่าใครเป็นผู้เรียกใช้ มันสนใจแค่ว่าคำสั่งและ payloads ถูกต้อง ซึ่งนำเราไปสู่กฎข้อเดียวที่ทำให้ทุกอย่างน่าเชื่อถือ

พิธีกรรมการเขียนที่ Agent ต้องปฏิบัติตาม

คำสั่งจัดทำเอกสารที่สร้างทรัพยากรจะรับไฟล์ JSON Agent ของคุณไม่ควรสร้าง JSON ด้วยตนเองจากความจำ ชื่อฟิลด์ที่โมเดลสร้างขึ้นเองคือสาเหตุอันดับหนึ่งของความล้มเหลวในการรัน CLI มาพร้อมกับ schema ที่ถูกต้องสำหรับทุกการเขียน และลำดับที่ถูกต้องจะประกอบด้วยสี่ขั้นตอนเสมอ:

# 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

นำลูปนี้ไปใส่ในคำแนะนำของ agent มันเปลี่ยนจาก “โมเดลสร้างฟิลด์ขึ้นมาเอง” เป็น “ตัวตรวจสอบปฏิเสธมันบนเครื่องของฉัน” ซึ่งเป็นความแตกต่างระหว่างการรันที่สะอาดกับการ build ที่ล้มเหลว นี่คือบล็อกกฎที่คุณสามารถวางลงใน system prompt ของ agent หรือไฟล์ 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.

ห้าบรรทัดเหล่านั้นคือสิ่งที่แยกแยะ agent ที่เผยแพร่เอกสารได้อย่างน่าเชื่อถือออกจาก agent ที่คาดเดา payloads จนล้มเหลว

ขั้นตอนที่ 1: สร้างข้อมูลอ้างอิงจาก Endpoint และ Schema

ใน Apidog ข้อมูลอ้างอิง API ของคุณจะถูกสร้างขึ้นจาก endpoints และ data schemas ในโปรเจกต์ ดังนั้น งานแรกของ agent คือการสร้างสิ่งเหล่านั้น สมมติว่าคุณบอกมันว่า:

“เพิ่ม endpoint POST /refunds ที่รับ Order ID และจำนวนเงิน และจัดทำเอกสารการตอบกลับที่สำเร็จและข้อผิดพลาดในการตรวจสอบ”

agent จะสร้างโมเดลข้อมูลที่นำมาใช้ซ้ำได้ก่อน จากนั้นจึงสร้าง endpoint ที่อ้างอิงถึงโมเดลนั้น การรัน apidog cli-schema get schema-create แสดงให้เห็นว่า data schema จะรับ name และอ็อบเจกต์ jsonSchema มาตรฐาน ดังนั้น agent จึงเขียนไฟล์เช่น 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" }
    }
  }
}

ตรวจสอบความถูกต้องและสร้าง:

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

ตอนนี้คือ endpoint schema สำหรับ endpoint-create ต้องมี method และ path และช่วยให้คุณสามารถอ้างอิงถึงโมเดลข้อมูลที่คุณเพิ่งสร้างขึ้นด้วย $ref ในรูปแบบ #/definitions/{schemaId} agent เขียนไฟล์ 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

เอกสารอ้างอิงสำหรับ /refunds มีอยู่แล้ว ซึ่งสร้างขึ้นจากคำจำกัดความเดียวกันกับที่ทีมของคุณแก้ไข ไม่มีขั้นตอน “ส่งออกเอกสาร” แยกต่างหากสำหรับข้อมูลอ้างอิง มันจะใช้งานได้ทันทีในโปรเจกต์เมื่อ endpoint ถูกสร้างขึ้น นั่นคือผลตอบแทนของการใช้แหล่งที่มาแบบ schema-first: ข้อมูลอ้างอิงจะไม่คลาดเคลื่อน เพราะมัน คือ schema นั่นเอง

ขั้นตอนที่ 2: เขียนคู่มือ ไม่ใช่แค่ข้อมูลอ้างอิง

ข้อมูลอ้างอิงที่สร้างจาก schemas เป็นเพียงครึ่งหนึ่งของเอกสารที่ดี อีกครึ่งหนึ่งคือข้อความอธิบาย: หน้าเริ่มต้นใช้งาน, คำแนะนำการยืนยันตัวตน, บันทึกการย้ายระบบ ใน Apidog สิ่งเหล่านี้จะอยู่ใน docs tree ของโปรเจกต์ในรูปแบบเอกสาร Markdown ซึ่งจัดการโดยกลุ่มคำสั่ง doc

schema ของ doc-create ต้องการเพียง name เท่านั้น; content จะเก็บ Markdown และ folderId จะระบุตำแหน่งในโครงสร้าง (0 คือ root) ดังนั้น quickstart ที่ agent ร่างขึ้นจะกลายเป็น 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

นี่คือจุดที่ agent แสดงประสิทธิภาพ ขอให้มัน “เขียน quickstart ที่นำพานักพัฒนาใหม่ตั้งแต่ API key ไปจนถึงการคืนเงินครั้งแรก” แล้วมันจะร่าง Markdown, ห่อหุ้มใน payload ที่ schema คาดหวัง, ตรวจสอบความถูกต้อง, และสร้างเอกสาร ไม่ต้องใช้เบราว์เซอร์, ไม่ต้องคัดลอกวาง เนื่องจากเนื้อหาเป็นเพียงฟิลด์สตริง Agent จึงสามารถเขียนคู่มือได้ยาวหรือละเอียดตามที่งานต้องการ

ขั้นตอนที่ 3: เผยแพร่เว็บไซต์เอกสาร

เมื่อมีข้อมูลอ้างอิงและคู่มือพร้อม Agent ก็สามารถเผยแพร่จาก terminal ได้เช่นกัน มีสองกลุ่มคำสั่งที่จัดการเรื่องนี้ และความแตกต่างในการตั้งชื่อหนึ่งอย่างที่ทำให้คนสับสนอยู่เสมอ:

doc: เอกสาร Markdown ภายใน API tree ของโปรเจกต์ (สิ่งที่คุณสร้างในขั้นตอนที่ 2)
docs-site: เว็บไซต์เอกสารสาธารณะที่โฮสต์ไว้
shared-doc: ลิงก์ที่สามารถแชร์ได้สำหรับส่งให้คู่ค้า ไม่ใช่เว็บไซต์เต็มรูปแบบ

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

ใช้ docs-site เมื่อคุณต้องการสร้างเว็บไซต์สาธารณะจาก terminal และใช้ shared-doc เมื่อคุณเพียงแค่ต้องการลิงก์เพื่อส่งให้ใครบางคน เนื่องจากทั้งสองเป็นคำสั่ง การเผยแพร่จึงกลายเป็นขั้นตอนที่เขียนสคริปต์ซึ่ง agent รันหลังจากทุกการเปลี่ยนแปลงเอกสาร; เว็บไซต์ที่โฮสต์จะสะท้อนการอัปเดตทันทีที่คำสั่งส่งคืนผลลัพธ์

ขั้นตอนที่ 4 (ทางเลือก): ส่งออกสำเนาที่สามารถพกพาได้

บางครั้งคุณอาจต้องการเอกสารในรูปแบบไฟล์: หน้า HTML สำหรับโฮสต์ที่อื่น, Markdown สำหรับ static-site generator, หรือ OpenAPI สำหรับส่งต่อให้ระบบปลายน้ำ คำสั่ง 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

หากโปรเจกต์ของคุณมีหลายบริการและคุณต้องการจัดทำเอกสารเพียงบางส่วนเท่านั้น apidog export --help จะแสดงแฟล็ก --scope, --api-ids, และ --folder-ids สำหรับจำกัดขอบเขตของผลลัพธ์ โปรเจกต์เดียวสามารถส่งออกไฟล์เอกสารหนึ่งไฟล์ต่อหนึ่งบริการได้ด้วยวิธีนั้นตัวอย่างฉบับเต็ม ตั้งแต่ต้นจนจบ

นี่คือลูปทั้งหมดในรูปแบบคำขอภาษาธรรมดาหนึ่งรายการ และคำสั่งที่ agent รันเพื่อตอบสนองคำขอนั้น

คุณ: “เราเพิ่งเพิ่มบริการชำระเงินพร้อม POST /refunds และ GET /refunds/{id} จัดทำเอกสารทั้งสองรายการ เขียนคู่มือสั้นๆ อธิบาย idempotency keys และเผยแพร่ไปยังเว็บไซต์เอกสารของเรา”

Agent, ตามกฎที่กำหนดไว้, จะรัน:

# 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

คุณตรวจสอบ diff ที่ได้ และบริการชำระเงินก็ได้รับการจัดทำเอกสารและพร้อมใช้งาน สิ่งที่เคยเป็นงานที่ต้องใช้เวลาเปลี่ยนบริบทตลอดบ่าย กลายเป็นเพียงคำขอและการตรวจสอบ

เชื่อมต่อเข้ากับ Agent Loop หรือ CI

เนื่องจากทุกขั้นตอนเป็นคำสั่ง กระบวนการทั้งหมดจึงสามารถรวมเข้ากับ CI หรือ task loop ของ agent ได้ ขั้นตอนขั้นต่ำที่สร้างและคอมมิตข้อมูลอ้างอิง Markdown ของคุณใหม่ทุกครั้งที่ 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

สำหรับภาพรวมที่สมบูรณ์ยิ่งขึ้นของการรัน agent กับ CLI แบบ end-to-end โปรดดู From PRD to Testing Loop และ How to Set Up 5 AI Agents to Build a Complete API รูปแบบในทั้งสองกรณีก็เหมือนกันที่นี่: อธิบายเจตนา ให้ agent แปลเป็น CLI calls ที่ผ่านการตรวจสอบ และตรวจสอบผลลัพธ์

ข้อควรทราบเกี่ยวกับสิทธิ์หนึ่งข้อ

การเขียนไปยังโปรเจกต์ผ่าน agent อาจถูกจำกัดสิทธิ์ หากคำสั่ง create ถูกบล็อก แสดงว่าโปรเจกต์นั้นปิดการอนุญาตแก้ไขด้วย AI ภายนอกสำหรับ branch นั้น คุณมีสองทางเลือกที่ชัดเจน: เปิดใช้งานสิทธิ์แก้ไขโดยตรงในการตั้งค่าโปรเจกต์ → การตั้งค่าคุณสมบัติ → การตั้งค่าคุณสมบัติ AI (Apidog client 2.8.32+) หรือให้ agent ทำงานบน AI branch ที่แยกต่างหากและเปิด merge request คู่มือประกอบเกี่ยวกับการอัปเดต API spec ของคุณอธิบายขั้นตอนของ AI-branch ไว้อย่างครบถ้วน และสามารถนำมาใช้ได้เช่นเดียวกันเมื่อ agent กำลัง สร้าง เอกสารบน protected branch

ข้อผิดพลาดที่พบบ่อย

Agent สร้าง JSON ด้วยตนเอง นี่คือความล้มเหลวอันดับหนึ่ง บังคับใช้ cli-schema get → cli-schema validate → create ในคำแนะนำของ agent เพื่อให้มันทำงานจาก schema จริง ไม่ใช่จาก schema ที่คาดเดา
Project ID หายไป ทุกการเรียกใช้ doc, docs-site, และ export ต้องมี --project <projectId> ซึ่งเป็น ID จากการตั้งค่า ไม่ใช่ชื่อโปรเจกต์ที่อ่านได้ รายงาน “เกิดข้อผิดพลาด” ส่วนใหญ่มาจากสาเหตุนี้
สับสนระหว่าง doc, docs-site, และ shared-doc สิ่งเหล่านี้เป็นสามสิ่งที่ไม่เหมือนกัน: หน้า Markdown ในโครงสร้าง, เว็บไซต์ที่โฮสต์ไว้, และลิงก์สำหรับแชร์ ให้ agent ยืนยันว่างานหมายถึงสิ่งใดก่อนที่จะเขียน
ไม่ได้ตั้งค่า Token ใน CI apidog login จะจัดเก็บโทเค็นไว้ในเครื่องที่รันมัน CI runner ที่เพิ่งเริ่มต้นจะไม่มีโทเค็น ดังนั้นให้รัน login --with-token ใน job เดียวกันก่อนคำสั่งใดๆ และเก็บโทเค็นไว้ใน secret
$ref ที่ชี้ไปยังที่ที่ไม่ถูกต้อง เมื่อ endpoint อ้างอิงถึงโมเดลข้อมูลด้วย #/definitions/{schemaId} schema นั้นจะต้องมีอยู่ก่อน สร้าง schemas ก่อนที่จะสร้าง endpoints ที่ใช้ schema เหล่านั้น

คำถามที่พบบ่อย

AI agent ใดบ้างที่สามารถขับเคลื่อน Apidog CLI ได้? Agent ใดก็ได้ที่สามารถรันคำสั่ง shell ได้: Claude Code, Cursor, Codex และ coding agent อื่นๆ ที่คล้ายกัน CLI ไม่ขึ้นกับ agent; มันต้องการเพียงคำสั่งที่ถูกต้องและ payloads ที่ถูกต้องเท่านั้น
ฉันจำเป็นต้องมีแพ็คเกจแบบชำระเงินหรือไม่? ไม่จำเป็น Apidog ไม่ใช่โอเพนซอร์ส แต่แพ็คเกจฟรีร่วมกับ apidog-cli ครอบคลุมขั้นตอนการสร้างและเผยแพร่ที่อธิบายไว้ที่นี่
Agent สามารถเขียนทับเอกสารที่มีอยู่โดยไม่ตั้งใจได้หรือไม่? create จะเพิ่มทรัพยากรใหม่ การแก้ไขทรัพยากรที่มีอยู่ใช้ update ซึ่งทำงานแตกต่างกันและต้องการการป้องกันของตัวเอง; สิ่งนี้ครอบคลุมอยู่ใน คู่มือประกอบการอัปเดต API spec ของคุณ
สิ่งนี้แตกต่างจาก AI docs generator อย่างไร? เครื่องมือ AI docs ทั่วไปสร้างข้อความจากโค้ดของคุณ แต่นี่สร้างเอกสารที่มี โครงสร้าง ภายในแพลตฟอร์ม API ของคุณ (endpoints, schemas, คู่มือ และเว็บไซต์ที่เผยแพร่) จากแหล่งข้อมูลสดแหล่งเดียวที่ไม่สามารถคลาดเคลื่อนไปจากสิ่งที่ทีมของคุณแก้ไขได้

สรุป

Agent ที่สามารถรัน Apidog CLI ได้สามารถรับผิดชอบส่วนของการจัดทำเอกสารที่ผู้คนมักจะเลื่อนออกไปได้: มันสร้าง endpoints, เขียนคู่มือประกอบ, และเผยแพร่เว็บไซต์ ทั้งหมดนี้มาจากคำขอที่เป็นภาษามนุษย์ทั่วไป พร้อมด้วยการตรวจสอบ schema ที่ป้องกันทุกการเขียน บทบาทของคุณจะเปลี่ยนจากการเขียนเอกสารเป็นการตรวจสอบ diff กฎข้อเดียวที่ทำให้มันน่าเชื่อถือคือพิธีกรรมการเขียน: รับ schema, ตรวจสอบความถูกต้อง, แล้วจึงสร้าง มอบลูปนั้น, บล็อกกฎห้าบรรทัดข้างต้น, และ Project ID ให้กับ agent ของคุณ แล้วการจัดทำเอกสารจะไม่ใช่ภาระที่ล่าช้าตามหลังโค้ดอีกต่อไป ดาวน์โหลด Apidog เพื่อรับ CLI หรืออ่าน คู่มือฉบับสมบูรณ์ของ Apidog CLI สำหรับข้อมูลอ้างอิงคำสั่งทั้งหมด

button