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

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

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

นี่คือคู่มือการ เปลี่ยนแปลง ควบคู่ไปกับการให้ Agent สร้างเอกสาร API การสร้างเป็นการเพิ่มเข้าไปและมีความเสี่ยงต่ำ; การอัปเดตสัญญาที่มีอยู่คือจุดที่แนวป้องกันมีความสำคัญ ดังนั้นส่วนใหญ่ของคู่มือนี้จึงเกี่ยวกับการทำสิ่งนี้โดยไม่ทำให้เกิดความเสียหาย

“อัปเดตสเปก” ที่ CLI หมายถึงอะไร

สเปกของคุณใน Apidog คือชุดของเอนด์พอยต์และ data schema ในโปรเจกต์ การอัปเดตสเปกหมายถึงหนึ่งในสามคำสั่งต่อไปนี้:

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

ก่อนที่คุณจะชี้ Agent ไปยังคำสั่งใดๆ เหล่านี้ มีสองพฤติกรรมที่คุณต้องทำความเข้าใจ เพราะการเข้าใจผิดอาจทำให้สเปกเสียหายได้ อย่างแรกคือรูปแบบการอนุญาต และอย่างที่สองคือข้อผิดพลาดที่จะลบข้อมูลไปอย่างเงียบๆ

ข้อผิดพลาดที่จะทำให้คุณเดือดร้อน: การอัปเดตคือการแทนที่ทั้งหมด

นี่คือสิ่งสำคัญที่สุดที่คุณต้องสอน Agent ของคุณ คำสั่ง update ของ CLI ไม่ใช่ JSON Patch โดยจะส่งฟิลด์ที่คุณระบุโดยตรง; จะไม่รวมรายการใน array ด้วย ID หากคุณส่งการอัปเดตด้วย array parameters บางส่วนโดยตั้งใจจะเปลี่ยนพารามิเตอร์เดียว คุณจะไม่แก้ไขพารามิเตอร์นั้น คุณจะแทนที่ array ทั้งหมดด้วยพารามิเตอร์ที่คุณส่งไปเท่านั้น ส่วนที่เหลือจะหายไป

ลำดับที่ถูกต้องคือการอ่าน-แก้ไข-เขียนบน object ฉบับสมบูรณ์ เสมอ:

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

# 2. แก้ไขโครงสร้างทั้งหมดในเครื่อง (เก็บทุกฟิลด์ที่คุณไม่ได้เปลี่ยนไว้)

# 3. ตรวจสอบความถูกต้องของ object ทั้งหมดกับ schema
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

ระบุสิ่งนี้ในคำสั่งของ Agent ด้วยถ้อยคำที่เข้าใจง่าย: ห้ามส่ง object บางส่วนไปที่ update เด็ดขาด; ให้ดึง resource ทั้งหมด, แก้ไข, และส่งกลับไปทั้งชิ้นเสมอ. Agent ที่ข้ามขั้นตอน get จะละทิ้งฟิลด์ไปอย่างเงียบๆ Agent ที่รัน cli-schema validate ก่อนจะจับข้อผิดพลาดของตัวเองได้ก่อนที่จะส่งผลกระทบต่อโปรเจกต์

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

คุณสามารถให้สิทธิ์ Agent แก้ไข main branch ของคุณได้โดยตรง แต่อย่าเพิ่งทำในตอนเริ่มต้น Apidog มีกลไกการแยกส่วนที่สร้างขึ้นมาโดยเฉพาะ นั่นคือ AI branch ซึ่งออกแบบมาเพื่อการนี้โดยเฉพาะ: Agent สามารถแก้ไข resource โดยไม่แตะต้อง source branch และจะไม่มีการรวมกลับ (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 เพื่อให้มองเห็นต้นทางและวัตถุประสงค์ของ branch ได้อย่างชัดเจน ค่า --from ต้องเป็น main branch ของคุณหรือ sprint branch ปกติ ไม่ใช่ general branch ข้อดีอย่างหนึ่งคือ: AI branch ที่ไม่มีความแตกต่างจาก source จะถูกจัดเก็บอัตโนมัติหลังจาก 24 ชั่วโมง ดังนั้นการทดลองที่ถูกทิ้งร้างจะถูกลบออกไปเอง

ขั้นตอนที่ 2: นำเข้า resource ที่ Agent จะแก้ไข

AI branch เริ่มต้นจากที่ว่างเปล่า มันไม่ได้โคลน source branch โดยอัตโนมัติ ก่อนที่ Agent จะสามารถแก้ไขเอนด์พอยต์หรือ schema ที่มีอยู่แล้ว คุณต้องดึง resource นั้นเข้ามาใน branch ด้วย pick-to:

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

Resource ที่ Agent สร้าง ขึ้นใหม่บน branch ไม่จำเป็นต้องทำตามขั้นตอนนี้; เฉพาะ resource ที่มีอยู่ซึ่ง Agent ตั้งใจจะแก้ไขหรือลบเท่านั้น นี่คือขั้นตอนที่คนมักจะลืม: หากข้ามขั้นตอนนี้ไป Agent จะมี branch ที่ว่างเปล่าและไม่มีอะไรให้แก้ไข

ขั้นตอนที่ 3: ให้ Agent ทำการเปลี่ยนแปลง

ตอนนี้ Agent จะรันวงจรการอ่าน-แก้ไข-เขียนจากที่กล่าวไว้ก่อนหน้า แต่โดยระบุ --branch ไปยัง AI branch การแก้ไขทั้งหมดจะถูกจำกัดอยู่ภายใน:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json

Main branch ของคุณจะไม่ถูกแตะต้องตลอดเวลานี้ หาก Agent ทำผิดพลาด ขอบเขตความเสียหายก็จำกัดอยู่แค่ branch ที่สามารถทิ้งไปได้

ขั้นตอนที่ 4: ตรวจสอบ แล้วค่อยรวม (Merge)

การเปลี่ยนแปลงใน AI branch จะไม่ถูกเขียนกลับโดยอัตโนมัติ เมื่อ Agent ทำงานเสร็จสิ้น คุณ คือผู้ตัดสินใจว่าจะเกิดอะไรขึ้น หากเป้าหมายได้รับการป้องกัน ให้เปิด merge request แทนการรวมโดยตรง:

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

ตรวจสอบความแตกต่าง (diff), อนุมัติ, และการเปลี่ยนแปลงที่ผ่านการตรวจสอบก็จะถูกนำไปรวมใน main การรวมโดยตรงจาก CLI ต้องได้รับอนุญาตให้แก้ไขโดยตรงบนทั้ง source และ target branch; หาก main branch ได้รับการป้องกัน ให้ใช้ merge-request และอนุมัติใน Apidog client

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

กฎเกณฑ์ที่เป็นนามธรรมนั้นง่ายต่อการพยักหน้าเห็นด้วย แต่ยากที่จะนำไปใช้ นี่คือตัวอย่างที่เป็นรูปธรรม สมมติว่าคุณต้องการเปลี่ยนชื่อ amount เป็น amountCents ใน data model Refund เนื่องจากคุณกำลังจะเปลี่ยนไปใช้หน่วยเซ็นต์ที่เป็นจำนวนเต็ม

คุณบอก Agent ว่า: “เปลี่ยนชื่อฟิลด์ amount ใน Refund schema เป็น amountCents และทำให้เป็นจำนวนเต็ม” โดยทำตามกฎของมัน Agent จะ:

# 1. ดึง schema ปัจจุบันฉบับเต็มบน AI branch
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"

มันจะดึง object ทั้งหมดกลับมาและแก้ไข schema ทั้งหมด โดยเก็บทุกฟิลด์ที่ไม่ได้แตะต้องไว้:

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

โปรดสังเกตว่าสิ่งใด ไม่ได้ เกิดขึ้น: มันไม่ได้ส่งแค่ property ที่เปลี่ยนแปลงไปเพียงอันเดียว แต่มันส่ง schema ทั้งหมดพร้อมกับ orderId และ reason ที่ยังคงสภาพเดิม เนื่องจาก update จะทำการแทนที่ทั้งหมด จากนั้น:

# 2. ตรวจสอบความถูกต้องของ object ฉบับสมบูรณ์
apidog cli-schema validate schema-create --file ./refund-full.json

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

คุณตรวจสอบความแตกต่าง (diff) ของ AI branch (เปลี่ยนชื่อฟิลด์เดียว ไม่มีการรบกวนส่วนอื่น) และทำการรวม นั่นคือระเบียบวินัยทั้งหมด: object ฉบับสมบูรณ์, ตรวจสอบแล้ว, บน branch, รวมหลังจากตรวจสอบ

ทำเครื่องหมายการเปลี่ยนแปลงที่อาจส่งผลกระทบก่อนการรวม

การเปลี่ยนชื่อฟิลด์ที่จำเป็นถือเป็นการเปลี่ยนแปลงที่ส่งผลกระทบ (breaking change): ลูกค้าใดๆ ที่ส่ง amount มาตอนนี้จะล้มเหลวในการตรวจสอบความถูกต้อง ชุดคำสั่งของ Agent ที่ดีจะทำให้โมเดล ระบุ การเปลี่ยนแปลงดังกล่าว แทนที่จะรวมไปอย่างเงียบๆ เพิ่มสิ่งนี้ในกฎของ Agent:

ก่อนที่จะรวมการเปลี่ยนแปลงสเปกใดๆ ให้จำแนกประเภท:
- ไม่ส่งผลกระทบ (non-breaking) (ฟิลด์เสริมใหม่, เอนด์พอยต์ใหม่, ข้อจำกัดที่ผ่อนปรนขึ้น) → สรุปและดำเนินการต่อไปยัง merge-request
- ส่งผลกระทบ (breaking) (เปลี่ยนชื่อ/ลบฟิลด์, ฟิลด์จำเป็นใหม่, ประเภทที่เข้มงวดขึ้น) → หยุด.
  รายงานการเปลี่ยนแปลงที่ส่งผลกระทบและเอนด์พอยต์ที่ได้รับผลกระทบ และรอการอนุมัติที่ชัดเจนจากมนุษย์

AI branch คือสิ่งที่ทำให้การบังคับใช้กฎนี้ปลอดภัย: เพราะไม่มีการรวมอัตโนมัติ ดังนั้น “หยุดและรายงาน” จึงเป็นจุดตรวจสอบที่แท้จริง ไม่ใช่การแข่งกับงานเขียนที่เกิดขึ้นไปแล้ว

การอัปเดตจากไฟล์ OpenAPI แทน

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

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

import รองรับ OpenAPI 3.x, Swagger 2.0, Postman และอื่นๆ รันมันกับ AI branch ก่อน เพื่อให้คุณสามารถตรวจสอบการเปลี่ยนแปลงสเปกที่เข้ามาได้ก่อนที่จะไปถึง main หลังจากการรวมแล้ว ให้ export สเปกที่ปรับปรุงแล้วกลับออกมาเพื่อยืนยันผลลัพธ์:

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

เส้นทางนี้ดีที่สุดเมื่อแหล่งข้อมูลความจริง (source of truth) อยู่ภายนอก Apidog และคุณกำลังทำการซิงค์เข้ามา เส้นทาง update แบบฟิลด์ต่อฟิลด์ดีที่สุดเมื่อ Apidog เป็น แหล่งข้อมูลความจริง และคุณกำลังทำการเปลี่ยนแปลงที่เจาะจง

เมื่อ Agent ทำผิดพลาด: การย้อนกลับ (Rollback)

เหตุผลที่ต้องทำงานบน AI branch คือความผิดพลาดสามารถแก้ไขได้ง่าย หาก Agent สร้างการเปลี่ยนแปลงที่คุณไม่ต้องการ คุณก็ไม่เคยรวมมันเข้าด้วยกัน ดังนั้น main branch จึงยังคงถูกต้อง เพียงแค่จัดเก็บ (archive) branch นั้นแล้วดำเนินการต่อไป:

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

เนื่องจาก AI branch ที่ไม่มีความแตกต่างที่ได้รับการยอมรับจะถูกจัดเก็บอัตโนมัติหลังจาก 24 ชั่วโมงอยู่แล้ว แม้แต่การทดลองที่ถูกลืมก็จะถูกลบออกไปเอง ลองเปรียบเทียบกับ Agent ที่แก้ไข main branch โดยตรง ซึ่งการ update ที่ผิดพลาดจะมีผลทันที และทางเลือกเดียวของคุณคือถังรีไซเคิลหรือการย้อนกลับด้วยตนเอง branch ไม่ใช่เรื่องยุ่งยากทางราชการ; มันคือปุ่มเลิกทำ (undo button)

หมายเหตุเกี่ยวกับสิทธิ์การอนุญาต

หากการ update หรือ import ถูกบล็อก แสดงว่าโปรเจกต์ได้ปิดใช้งาน External AI Edit Permissions ไว้ นี่คือประตูที่ตั้งใจบล็อกไว้ และขั้นตอน AI branch ข้างต้นคือคำตอบสำหรับปัญหานี้: Agent จะแก้ไข branch ที่แยกออกมา และคุณเป็นผู้อนุมัติการรวม หากคุณต้องการให้สิทธิ์แก้ไขโดยตรง ตัวเลือกจะอยู่ที่ Project Settings → Feature Settings → AI Feature Settings (Apidog client 2.8.32+) เมื่อ Agent พบข้อจำกัดด้านสิทธิ์การอนุญาต อย่าให้มันหาทางแก้ไขเองอย่างเงียบๆ; แต่ให้แสดงทางเลือกให้มนุษย์ตัดสินใจ

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

• การอัปเดตบางส่วนลบฟิลด์. เป็นข้อผิดพลาดที่สร้างความเสียหายมากที่สุดและพบบ่อยที่สุด update คือการแทนที่; ไม่ใช่การรวม ดึง object ทั้งหมด, แก้ไขทั้งชิ้น, ตรวจสอบ, แล้วจึงเขียน หากฟิลด์หายไป Agent ได้ส่ง payload บางส่วนไป
• การแก้ไข resource ที่มีอยู่บน AI branch โดยไม่ได้นำเข้ามาก่อน. branch เริ่มต้นจากที่ว่างเปล่า ให้ pick-to resource เข้ามาใน branch ก่อน มิฉะนั้น Agent จะไม่มีอะไรให้แก้ไข
• ระบุ --from ผิดสำหรับ AI branch. source ต้องเป็น main หรือ sprint branch เท่านั้น ห้ามเป็น general branch คำสั่ง branch create จะแจ้งข้อผิดพลาดหากคุณระบุผิด
• การข้ามการตรวจสอบ (validation). cli-schema validate จะจับ payload ที่ไม่ถูกต้องบนเครื่องของคุณ Agent ที่เขียนโดยไม่ตรวจสอบจะเปลี่ยนข้อผิดพลาดในการพิมพ์เป็นการเรียก API ที่ล้มเหลว หรือแย่กว่านั้นคือการรวมที่ไม่ถูกต้อง
• การรวมการเปลี่ยนแปลงที่ส่งผลกระทบอย่างเงียบๆ. หากไม่มีกฎการจำแนกประเภทก่อน Agent จะทำการเปลี่ยนชื่อฟิลด์ที่จำเป็นและรวมมันเข้าด้วยกันอย่างสบายใจ ทำให้การตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบเป็นจุดตรวจสอบที่ชัดเจน

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

• ฉันสามารถให้ 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 จะไม่สร้างชื่อฟิลด์ที่ไม่ถูกต้อง (hallucinate)? วงจร cli-schema get → validate คือแนวป้องกัน Payload ที่มีฟิลด์ที่สร้างขึ้นเองจะล้มเหลวในการตรวจสอบความถูกต้องในเครื่อง ก่อนที่จะไปถึงโปรเจกต์

สรุป

การให้ Agent อัปเดต API spec ของคุณนั้นปลอดภัยเมื่อมีสามสิ่งเป็นจริง: มันทำงานบน AI branch ที่แยกออกมา, มันถือว่าทุกการอัปเดตเป็นการอ่าน-แก้ไข-เขียนแบบเต็มรูปแบบแทนที่จะเป็น patch, และมนุษย์อนุมัติการรวม Apidog CLI มอบทั้งสามสิ่งนี้ให้คุณในรูปแบบของคำสั่ง ซึ่งหมายความว่าวงจรทั้งหมด (แก้ไข, ตรวจสอบ, รีวิว) สามารถเขียนสคริปต์และตรวจสอบได้ และการเปลี่ยนแปลงที่ไม่ดีก็อยู่ห่างจากคำสั่ง archive เพียงไม่กี่คลิก

ตั้งค่า AI branch, มอบกฎการอ่าน-แก้ไข-เขียน และจุดตรวจสอบการเปลี่ยนแปลงที่ส่งผลกระทบให้กับ Agent, แล้วการบำรุงรักษา spec ก็จะกลายเป็นการตรวจสอบความแตกต่างที่คุณอนุมัติ แทนที่จะเป็นงานจุกจิกที่คุณมักจะผัดวันประกันพรุ่ง ดาวน์โหลด Apidog เพื่อรับ CLI และใช้ร่วมกับ การให้ Agent สร้างเอกสารของคุณ เพื่อครอบคลุมวงจรการสร้างและการบำรุงรักษาทั้งหมด