วิธีให้ AI Agent อัปเดต API Spec ด้วย Apidog CLI

การแก้ไข API spec ด้วยมือมักเป็นงานละเอียดและเสี่ยง ตั้งแต่เปลี่ยนชื่อฟิลด์ เพิ่มค่า enum ไปจนถึงปรับฟิลด์ให้เป็น required ทุกการเปลี่ยนแปลงต้องอยู่ในตำแหน่งที่ถูกต้องโดยไม่กระทบ endpoint หรือ schema ที่อ้างอิงอยู่ งานลักษณะนี้เหมาะกับ AI agent แต่ต้องมีรั้วป้องกันเพื่อไม่ให้ agent ทำลาย schema ทั้งหมด

ลองใช้ Apidog วันนี้

คุณทำได้ด้วย Apidog CLI ซึ่งมีสิ่งที่ agent ต้องใช้เพื่อแก้ไข spec อย่างรับผิดชอบ: ตรวจสอบ schema ก่อนเขียน, แยกงานบน branch และส่ง merge request ให้มนุษย์ตรวจสอบก่อนรวม

คู่มือนี้เน้นการ อัปเดต spec ควบคู่ไปกับการให้ agent สร้างเอกสาร API การสร้าง resource ใหม่มีความเสี่ยงต่ำกว่า แต่การเปลี่ยนสัญญา API ที่มีอยู่ต้องมีขั้นตอนป้องกันที่ชัดเจน

“อัปเดตสเปก” ด้วย CLI คืออะไร

API spec ใน Apidog ประกอบด้วย endpoint และ data schema ภายในโปรเจกต์ โดยการอัปเดตมี 3 รูปแบบหลัก:

• endpoint update: เปลี่ยน path, parameter หรือ response
• schema update: เปลี่ยน data model ที่ endpoint อ้างอิง
• import: นำเข้าไฟล์ OpenAPI ใหม่เพื่อเปรียบเทียบและซิงก์กับโปรเจกต์

ก่อนมอบคำสั่งเหล่านี้ให้ agent ต้องเข้าใจ 2 เรื่อง:

1. รูปแบบสิทธิ์การแก้ไข
2. พฤติกรรมของคำสั่ง update ที่อาจลบข้อมูลได้หากใช้งานผิด

ข้อควรระวังสำคัญ: update คือการแทนที่ทั้ง object

คำสั่ง update ของ CLI ไม่ใช่ JSON Patch และไม่ได้ merge array ตาม ID

ตัวอย่างเช่น หาก endpoint มี parameters หลายรายการ แล้วคุณส่ง payload ที่มีเพียง parameter เดียวเพราะต้องการแก้ไขค่าเดียว CLI จะถือว่า array ที่ส่งมาคือรายการทั้งหมด ส่วน parameter อื่นจะหายไป

ดังนั้นให้ agent ใช้กระบวนการ อ่าน → แก้ไข → ตรวจสอบ → เขียนกลับ กับ object ฉบับเต็มเสมอ

# 1. ดึงข้อมูล endpoint ปัจจุบันทั้งหมด
apidog endpoint get <endpointId> --project <projectId>

# 2. แก้ไข object ฉบับเต็มในเครื่อง
# เก็บทุกฟิลด์ที่ไม่ได้เปลี่ยนไว้

# 3. ดึง schema ของ payload และตรวจสอบก่อนเขียน
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. เขียน object ฉบับเต็มกลับไป
apidog endpoint update <endpointId> \
  --project <projectId> \
  --file ./endpoint-full.json

เพิ่มกฎนี้ลงใน prompt หรือ instruction ของ agent โดยตรง:

ห้ามส่ง object บางส่วนไปที่ update เด็ดขาด
ให้ดึง resource ทั้งหมด แก้ไขเฉพาะส่วนที่ต้องการ
ตรวจสอบ payload และส่ง object ฉบับเต็มกลับไปเสมอ

หาก agent ข้าม get อาจทำให้ฟิลด์เดิมหายไปโดยไม่แสดงข้อผิดพลาดชัดเจน ส่วน cli-schema validate ช่วยจับ payload ที่ผิดก่อนส่งผลกระทบถึงโปรเจกต์

เส้นทางที่ปลอดภัย: ให้ agent ทำงานบน AI branch

แม้จะสามารถให้ agent แก้ไข main branch ได้โดยตรง แต่ควรเริ่มจาก AI branch ก่อน

AI branch แยกพื้นที่ทำงานของ agent ออกจาก source branch โดย agent สามารถแก้ไข resource ได้ แต่จะไม่มีอะไรถูก merge กลับจนกว่าคุณจะอนุมัติ คิดเสียว่าเป็น pull request สำหรับ API spec

ขั้นตอนที่ 1: สร้าง AI branch

apidog branch create --project <projectId> --type ai \
  --from main \
  --name "ai/20260713-from-main-refund-fields"

ใช้รูปแบบการตั้งชื่อที่ค้นหาและตรวจสอบง่าย:

ai/YYYYMMDD-from-source-feature

ตัวอย่าง:

ai/20260713-from-main-refund-fields

ข้อควรรู้:

• ค่า --from ต้องเป็น main branch หรือ sprint branch ปกติ
• ห้ามใช้ general branch เป็นต้นทาง
• AI branch ที่ไม่มีความแตกต่างจาก source จะถูก archive อัตโนมัติหลัง 24 ชั่วโมง

ขั้นตอนที่ 2: นำ resource ที่ต้องแก้ไขเข้า AI branch

AI branch เริ่มจากว่างเปล่าและไม่ได้ clone resource จาก source branch ให้อัตโนมัติ

ก่อนแก้ไข endpoint หรือ schema เดิม ให้ใช้ pick-to นำ resource เข้ามาใน branch:

apidog branch pick-to --project <projectId> --type ai \
  --from main \
  --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>

ทำขั้นตอนนี้เมื่อ agent ต้องการแก้ไขหรือลบ resource ที่มีอยู่แล้ว

Resource ที่สร้างใหม่บน AI branch ไม่จำเป็นต้อง pick-to ก่อน

หากข้ามขั้นตอนนี้ agent จะทำงานบน branch ที่ว่างเปล่าและไม่มี resource ให้แก้ไข

ขั้นตอนที่ 3: ให้ agent แก้ไขบน AI branch

ตอนนี้ให้ agent ใช้วงจรอ่าน-แก้ไข-เขียน โดยระบุ --branch ทุกครั้ง

# อ่าน endpoint จาก AI branch
apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

# แก้ไข payload ฉบับเต็ม ตรวจสอบแล้วจึงเขียนกลับ
apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json

Main branch จะไม่ถูกแก้ไขระหว่างขั้นตอนนี้ หาก agent ทำผิดพลาด ความเสียหายจะอยู่เฉพาะใน branch ที่สามารถ archive ทิ้งได้

ขั้นตอนที่ 4: ตรวจสอบ diff แล้วค่อย merge

การเปลี่ยนแปลงใน AI branch จะไม่ถูกเขียนกลับอัตโนมัติ เมื่อ agent ทำงานเสร็จ ให้ตรวจสอบ diff ก่อนเสมอ

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>

หาก main branch มีการป้องกัน ให้ใช้ merge-request และอนุมัติผ่าน Apidog client

การ merge ตรงจาก CLI ต้องมีสิทธิ์แก้ไขโดยตรงทั้ง source และ target branch

ตัวอย่าง: เปลี่ยนชื่อฟิลด์อย่างปลอดภัย

สมมติว่าคุณต้องการเปลี่ยนชื่อฟิลด์ amount เป็น amountCents ใน data model Refund และเปลี่ยนชนิดข้อมูลเป็น integer เพราะจะเก็บหน่วยเป็นเซ็นต์

คำสั่งที่ให้ agent:

เปลี่ยนชื่อฟิลด์ amount ใน Refund schema เป็น amountCents และกำหนดให้เป็นจำนวนเต็ม

1. ดึง schema ฉบับเต็มจาก AI branch

apidog schema get <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields"

2. แก้ไข schema ทั้งหมด ไม่ใช่เฉพาะฟิลด์ที่เปลี่ยน

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}

จุดสำคัญคือ schema ยังคงมี orderId และ reason อยู่ครบ เพราะ update แทนที่ object ทั้งหมด

3. ตรวจสอบและเขียนกลับไปยัง AI branch

# ตรวจสอบ payload ฉบับเต็ม
apidog cli-schema validate schema-create --file ./refund-full.json

# เขียน schema กลับไปยัง AI branch
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json

จากนั้นตรวจสอบ diff ให้แน่ใจว่าเปลี่ยนเฉพาะ:

• amount → amountCents
• type → integer
• required field → amountCents

แล้วจึง merge

ทำเครื่องหมาย breaking change ก่อน merge

การเปลี่ยนชื่อฟิลด์ required เป็น breaking change เพราะ client ที่ยังส่ง amount จะไม่ผ่าน validation

เพิ่มกฎการจัดประเภทการเปลี่ยนแปลงลงใน instruction ของ agent:

ก่อน merge การเปลี่ยนแปลง API spec ทุกครั้ง ให้จำแนกประเภทดังนี้

- Non-breaking:
  ฟิลด์ optional ใหม่, endpoint ใหม่, constraint ที่ผ่อนปรนขึ้น
  → สรุปผลและดำเนินการต่อไปยัง merge-request

- Breaking:
  เปลี่ยนชื่อหรือลบฟิลด์, เพิ่ม required field, ทำให้ type เข้มงวดขึ้น
  → หยุดการทำงาน
  → รายงาน breaking change และ endpoint ที่ได้รับผลกระทบ
  → รอการอนุมัติอย่างชัดเจนจากมนุษย์

AI branch ทำให้กฎนี้เป็นจุดตรวจสอบจริง เพราะ agent ยังไม่สามารถส่งการเปลี่ยนแปลงเข้า main ได้เอง

อัปเดตจากไฟล์ OpenAPI

หากการเปลี่ยนแปลงมีอยู่ในไฟล์ OpenAPI อยู่แล้ว เช่น สร้างจากโค้ด ได้จากทีมอื่น หรือแก้ไขในระบบภายนอก ให้ import ไฟล์แทนการแก้ทีละฟิลด์

apidog import --project <projectId> \
  --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"

import รองรับ OpenAPI 3.x, Swagger 2.0, Postman และรูปแบบอื่น ๆ

แนวทางที่ปลอดภัย:

1. Import ลง AI branch ก่อน
2. ตรวจสอบ diff ของ spec ที่เข้ามา
3. Merge เมื่ออนุมัติแล้ว
4. Export spec กลับมาเพื่อตรวจสอบผลลัพธ์

apidog export --project <projectId> \
  --format openapi \
  --oas-version 3.1 \
  --output ./openapi.json

เลือกแนวทางให้เหมาะกับ source of truth:

• ใช้ import เมื่อ OpenAPI file เป็น source of truth ภายนอก Apidog
• ใช้ update เมื่อ Apidog เป็น source of truth และต้องการแก้ไขเฉพาะจุด

เมื่อ agent ทำผิดพลาด: Rollback ด้วยการ archive branch

หาก agent สร้างการเปลี่ยนแปลงที่ไม่ต้องการบน AI branch คุณไม่จำเป็นต้อง revert main branch เพราะยังไม่ได้ merge

เพียง archive branch:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> \
  --type ai

AI branch ที่ไม่มีความแตกต่างที่ได้รับการยอมรับจะถูก archive อัตโนมัติหลัง 24 ชั่วโมงอยู่แล้ว

นี่คือข้อได้เปรียบหลักของ branch: ไม่ใช่งานเอกสารเพิ่ม แต่เป็นปุ่ม undo สำหรับ API spec

หมายเหตุเรื่องสิทธิ์การอนุญาต

หาก update หรือ import ถูกบล็อก อาจเป็นเพราะโปรเจกต์ปิดใช้งาน External AI Edit Permissions

ทางเลือกที่ปลอดภัยคือให้ agent แก้ไขบน AI branch แล้วให้มนุษย์อนุมัติการ merge

หากต้องการเปิดสิทธิ์แก้ไขโดยตรง ให้ตั้งค่าที่:

Project Settings → Feature Settings → AI Feature Settings

รองรับใน Apidog client 2.8.32+

เมื่อ agent พบข้อจำกัดเรื่องสิทธิ์ อย่าให้ agent พยายามหาทางข้ามเอง ให้รายงานสถานะและเสนอทางเลือกให้มนุษย์ตัดสินใจ

ปัญหาที่พบบ่อย

• อัปเดตบางส่วนแล้วฟิลด์หาย
  
  update แทนที่ object ทั้งหมด ไม่ได้ merge payload ให้ดึง object เต็ม แก้ไข ตรวจสอบ และเขียนกลับทั้งชิ้น

• แก้ไข resource บน AI branch โดยไม่ pick-to ก่อน
  
  AI branch เริ่มจากว่างเปล่า ต้องนำ resource เดิมเข้ามาก่อน

• ระบุ --from ผิดตอนสร้าง AI branch
  
  ต้นทางต้องเป็น main หรือ sprint branch ไม่ใช่ general branch

• ข้าม validation
  
  ใช้ cli-schema validate ก่อนเขียนทุกครั้ง เพื่อตรวจพบ payload ที่ไม่ถูกต้องในเครื่อง

• merge breaking change โดยไม่มีการอนุมัติ
  
  ให้ agent จำแนก breaking change และหยุดรอการอนุมัติจากมนุษย์

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

ฉันสามารถให้ agent แก้ไข main branch โดยตรงได้หรือไม่?

ทำได้หากเปิด External AI Edit Permissions แต่การเริ่มต้นบน AI branch ปลอดภัยกว่า เพราะไม่มีอะไรไปถึง main จนกว่าจะผ่านการตรวจสอบและอนุมัติ

branch merge กับ merge-request ต่างกันอย่างไร?

branch merge เขียนการเปลี่ยนแปลงทันทีและต้องใช้สิทธิ์แก้ไขโดยตรงบนทั้งสอง branch

merge-request สร้างคำขอที่ตรวจสอบได้ เหมาะเมื่อ main branch ได้รับการป้องกัน

Agent ต้องติดตั้งแอปเดสก์ท็อป Apidog หรือไม่?

ไม่จำเป็น CLI ทำงานแบบสแตนด์อโลน แอปเดสก์ท็อปจำเป็นเฉพาะการตั้งค่า External AI Edit Permissions ครั้งแรก

จะป้องกัน agent สร้างชื่อฟิลด์ที่ไม่มีอยู่จริงได้อย่างไร?

ใช้กระบวนการ:

cli-schema get → validate → update

Payload ที่มีฟิลด์ผิดหรือโครงสร้างไม่ถูกต้องจะไม่ผ่าน validation ก่อนส่งไปยังโปรเจกต์

สรุป

การให้ agent อัปเดต API spec ปลอดภัยขึ้นเมื่อทำครบ 3 เงื่อนไข:

1. ทำงานบน AI branch ที่แยกออกมา
2. ใช้การอ่าน-แก้ไข-เขียนแบบ full object แทน partial patch
3. ให้มนุษย์ตรวจสอบและอนุมัติก่อน merge

Apidog CLI ทำให้กระบวนการแก้ไข ตรวจสอบ และรีวิวเป็นสคริปต์ที่ทำซ้ำได้ และเมื่อการเปลี่ยนแปลงไม่ถูกต้อง คุณสามารถ archive branch ได้ทันที

ตั้งค่า AI branch กำหนดกฎ read-modify-write และเพิ่มจุดตรวจสอบ breaking change ให้ agent แล้วการดูแล API spec จะกลายเป็นการรีวิว diff ที่ควบคุมได้ แทนงานแก้ไขจุกจิกที่เสี่ยงต่อข้อผิดพลาด

ดาวน์โหลด Apidog เพื่อใช้งาน CLI และใช้ร่วมกับการให้ agent สร้างเอกสาร API เพื่อครอบคลุมทั้งวงจรการสร้างและบำรุงรักษา API