Thanawat Wongchai

Posted on May 19 • Originally published at apidog.com

วิธีสร้าง API ด้วย Cursor Composer 2.5

Cursor Composer 2.5 เร็วและคุ้มพอที่จะให้เอเจนต์ช่วยเขียน API client และ route handler ได้ แต่ปัญหาจะเกิดทันทีเมื่อโค้ดต้องคุยกับบริการจริง: โมเดลอาจสร้าง request ไปที่ /v2/orders ทั้งที่บริการของคุณเปิดจริงที่ /orders และต้องการ payload คนละแบบ โค้ดคอมไพล์ผ่าน แต่ใช้งานไม่ได้ และมักรู้ตัวหลังจากแก้ไปแล้วหลายไฟล์

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

บทความนี้เป็นเวิร์กโฟลว์แบบทำตามได้จริง: เชื่อม Composer 2.5 เข้ากับ API specification จริงผ่าน MCP ให้โมเดลสร้างโค้ดจากสัญญาจริง แล้วตรวจสอบผลลัพธ์ใน Apidog ก่อนส่งต่อให้ทีม หากคุณยังใหม่กับโมเดลนี้ อ่านพื้นฐานได้จาก คู่มือ Cursor Composer 2.5

ทำไมโมเดลเอเจนต์จึงเดารูปแบบ API

Composer 2.5 ถูกออกแบบมาสำหรับงานเอเจนต์หลายขั้นตอน เช่น:

“เพิ่ม client สำหรับ billing service และเชื่อมเข้ากับ payment flow”

โมเดลสามารถวางแผน แก้หลายไฟล์ และรัน test จนผ่านได้ ซึ่งเป็นการยกระดับจาก Composer 2

แต่จุดอ่อนคือ ถ้าโมเดลไม่มี API contract จริงอยู่ใน context มันจะเติมช่องว่างด้วย pattern ที่ “น่าจะถูก” เช่น:

endpoint แบบทั่วไป เช่น /api/users/{id} แทน /users/{userId}
field ที่ไม่มีอยู่จริงใน request body
authentication แบบ generic แทนรูปแบบจริงของ service
version prefix เช่น /v2 ทั้งที่ API จริงไม่มี

ผลลัพธ์มักดูสะอาด ผ่าน lint และดูเหมือน production-ready แต่ fail เมื่อยิงกับ server จริง เพราะ API ของคุณไม่ใช่ค่าเฉลี่ยของ API ทั้งอินเทอร์เน็ต

การ paste OpenAPI ทั้งไฟล์ลงใน prompt ช่วยได้บางส่วน แต่เปราะบางและกิน context มาก วิธีที่ดีกว่าคือให้โมเดลเข้าถึง API specification แบบมีโครงสร้างผ่าน MCP

วิธีแก้: ผูก Composer 2.5 กับ API specification จริงผ่าน MCP

Model Context Protocol หรือ MCP คือมาตรฐานเปิดสำหรับให้โมเดล AI เข้าถึง tool และข้อมูลภายนอก Cursor รองรับ MCP server และ Apidog MCP server สามารถ expose API specification ใน Apidog ให้โมเดลอ่านเป็นข้อมูลที่ query ได้

แทนที่ Composer 2.5 จะเดาเอง มันสามารถอ่านข้อมูลจริง เช่น:

endpoint path
HTTP method
request schema
response schema
required field
auth requirement
error response

แนวคิดนี้คล้ายกับ การเขียนโค้ดแบบ Vibe ด้วย Apidog MCP server แต่ใช้กับโมเดลที่สามารถทำงานแบบ agentic end-to-end ได้มากขึ้น

ขั้นตอนที่ 1: เตรียม API specification ใน Apidog

ก่อนให้ Composer 2.5 เขียนโค้ด ให้ทำให้ API contract ใน Apidog เป็น source of truth ก่อน

สิ่งที่ควรตรวจสอบ:

endpoint path ตรงกับ service จริง
method ถูกต้อง เช่น GET, POST, PATCH, DELETE
request body มี required field ครบ
response schema ตรงกับ server
error response สำคัญถูกระบุไว้ เช่น 400, 401, 409, 422
auth header หรือ token scheme ถูกต้อง
example request/response ใช้งานได้จริง

หากคุณมี OpenAPI หรือ Postman collection อยู่แล้ว สามารถนำเข้า Apidog ได้โดยตรง จากนั้นปรับ schema ให้เป็นปัจจุบัน เพราะนี่คือข้อมูลที่โมเดลจะใช้อ้างอิงตอน generate code

ขั้นตอนที่ 2: เชื่อม Apidog MCP server เข้ากับ Cursor

Cursor อ่าน MCP server จาก config ในโปรเจกต์ โดยทั่วไปคือไฟล์:

.cursor/mcp.json

ตัวอย่าง config:

{
  "mcpServers": {
    "apidog-api-spec": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--project=<your-project-id>"
      ],
      "env": {
        "APIDOG_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

ให้ใช้ command, project ID และ token ตามบัญชีของคุณจาก คู่มือการตั้งค่า Apidog MCP

หลังบันทึกไฟล์แล้ว ให้ restart Cursor เพื่อให้ Cursor โหลด MCP server ใหม่

ขั้นตอนที่ 3: ตรวจสอบว่า Composer 2.5 เห็น API specification แล้ว

เปิด agent session ใน Cursor และเลือกโมเดล composer-2.5

จากนั้นลอง prompt แบบ read-only ก่อน:

ใช้เซิร์ฟเวอร์ apidog-api-spec MCP เพื่อแสดงรายการ endpoint ภายใต้ resource orders
พร้อม method, path และ required fields สำหรับการสร้าง order

ถ้าการเชื่อมต่อถูกต้อง โมเดลควรตอบจาก API specification จริงของคุณ เช่น endpoint, field และ schema ที่ตรงกับโปรเจกต์

ถ้ามันตอบแบบกว้าง ๆ หรือใช้ pattern ทั่วไป เช่นเดา endpoint เอง ให้ตรวจสอบ:

.cursor/mcp.json อยู่ถูก path หรือไม่
APIDOG_ACCESS_TOKEN ถูกต้องหรือไม่
project ID ถูกต้องหรือไม่
restart Cursor แล้วหรือยัง
ชื่อ MCP server ใน prompt ตรงกับ config หรือไม่

ขั้นตอนที่ 4: ให้ Composer 2.5 สร้างโค้ดจาก API contract

เมื่อยืนยันว่า Composer 2.5 เห็น API spec แล้ว ให้สั่งงานโดยระบุให้ชัดว่า MCP server คือ source of truth

ตัวอย่าง prompt:

ใช้เซิร์ฟเวอร์ apidog-api-spec เป็น source of truth

เขียน TypeScript client สำหรับ Orders API โดยรวม:
- create-order
- get-order

ข้อกำหนด:
- path, method, request schema และ response schema ต้องตรงกับ API specification
- สร้าง type สำหรับ request และ response
- เพิ่ม error handling สำหรับ validation response 422 ตามที่ API specification กำหนด
- ห้ามเดา field หรือ endpoint ที่ไม่มีใน specification

ตัวอย่างโครงสร้างโค้ดที่ต้องการให้โมเดลสร้าง:

export type CreateOrderRequest = {
  // ให้ Composer 2.5 เติมจาก schema จริงใน Apidog
};

export type OrderResponse = {
  // ให้ Composer 2.5 เติมจาก response schema จริง
};

export async function createOrder(
  payload: CreateOrderRequest
): Promise<OrderResponse> {
  const response = await fetch("/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });

  if (response.status === 422) {
    const error = await response.json();
    throw new Error(`Validation failed: ${JSON.stringify(error)}`);
  }

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  return response.json();
}

จุดสำคัญคืออย่าให้โมเดล “คิดเอง” ว่า endpoint หรือ field ควรชื่ออะไร ให้มันอ่านจาก MCP ทุกครั้ง

ตรวจสอบก่อนเชื่อ: วงจรทดสอบด้วย Apidog

การให้โมเดลอ่าน API specification จริงช่วยลด hallucination ได้มาก แต่ยังไม่แทนที่การทดสอบ เพราะ:

specification อาจล้าหลัง service จริง
backend อาจมี behavior พิเศษที่ schema ไม่ได้อธิบายครบ
โมเดลอาจตีความ edge case ผิด

ใช้วงจรนี้หลังจาก Composer 2.5 สร้างโค้ด:

ยิง request จริงใน Apidog

นำ endpoint ที่โมเดลสร้างไปทดสอบใน Apidog กับ environment จริงหรือ mock ตรวจสอบ status code, response body และ auth behavior
เปรียบเทียบ response กับ type ที่สร้างขึ้น

ดูว่า response จริงตรงกับ TypeScript type หรือไม่ โดยเฉพาะ field ที่ optional, nullable หรือ nested object
บันทึก request ที่ถูกต้องเป็น test case

เมื่อ request ใช้งานได้ ให้บันทึกเป็น automated test เพื่อให้ CI จับ regression ได้ก่อนถึงผู้ใช้
ใช้ mock สำหรับ endpoint ที่ backend ยังไม่เสร็จ

ถ้า frontend ต้องทำงานก่อน backend พร้อม ให้ใช้ mock server ของ Apidog เพื่อคืน response ตาม schema จริง วิธีนี้เข้ากับรูปแบบใน AI agents and API testing

หลักการคือ:

โมเดลสร้าง draft จาก contract จริง ส่วนคุณยืนยันว่า draft นั้นทำงานกับ server จริง

ความเร็วจาก agent จะคุ้มค่าก็ต่อเมื่อไม่ต้องเสียเวลาตามแก้ bug ที่เกิดจาก API mismatch ภายหลัง

ตัวอย่าง workflow แบบครบวงจร

สมมติว่าคุณกำลังเพิ่มฟีเจอร์ refund ให้ payment service

1. เตรียม API contract

ใน Apidog มี endpoint และ schema สำหรับ refund อยู่แล้ว เช่น:

create refund
get refund status
error response กรณี duplicate request
header สำหรับ idempotency

2. เชื่อม MCP

ตั้งค่า Apidog MCP ใน Cursor และเลือก composer-2.5

3. สั่ง Composer 2.5

ใช้ prompt แบบเจาะจง:

ใช้ apidog-api-spec เป็น source of truth

สร้าง refund client และ React hook สำหรับเรียกใช้ refund API

ข้อกำหนด:
- ใช้ endpoint และ schema จาก API specification เท่านั้น
- รวม header idempotency-key ตามที่ specification กำหนด
- สร้าง TypeScript type สำหรับ request, success response และ error response
- เพิ่ม handling สำหรับ 409 duplicate request
- เพิ่ม test สำหรับ success case และ duplicate case

4. ให้โมเดลแก้หลายไฟล์

Composer 2.5 สามารถสร้างหลายส่วนพร้อมกัน เช่น:

src/api/refunds.ts
src/hooks/useCreateRefund.ts
src/types/refund.ts
src/api/refunds.test.ts

5. ตรวจสอบใน Apidog

เปิด Apidog แล้วทดสอบ:

request create refund สำเร็จ
request ซ้ำด้วย idempotency-key เดิม
response code 409 เมื่อเกิด duplicate ตาม contract

จากนั้นบันทึก request เหล่านี้เป็น test scenario

สิ่งที่ workflow นี้ช่วยหลีกเลี่ยงคือ client ที่ลืมส่ง idempotency-key แล้วทำให้เกิด refund ซ้ำใน staging หรือ production

Prompt template สำหรับใช้งานจริง

คุณสามารถใช้ template นี้ซ้ำกับ API อื่นได้:

ใช้เซิร์ฟเวอร์ apidog-api-spec MCP เป็น source of truth

งาน:
<อธิบาย feature ที่ต้องการสร้าง>

ข้อกำหนด:
- อ่าน endpoint, method, request schema และ response schema จาก API specification
- ห้ามเดา endpoint, field หรือ error response ที่ไม่มีใน specification
- สร้าง TypeScript type ให้ตรงกับ schema
- เพิ่ม error handling สำหรับ response code ที่ specification ระบุ
- เพิ่ม test สำหรับ success และ error case สำคัญ
- หลังแก้โค้ด ให้สรุปว่าใช้ endpoint ใดบ้างและ mapping schema อย่างไร

ตัวอย่างใช้งาน:

ใช้เซิร์ฟเวอร์ apidog-api-spec MCP เป็น source of truth

งาน:
สร้าง customer profile client และ hook สำหรับหน้า account settings

ข้อกำหนด:
- อ่าน endpoint, method, request schema และ response schema จาก API specification
- ห้ามเดา field ที่ไม่มีใน specification
- สร้าง TypeScript type สำหรับ get profile และ update profile
- เพิ่ม handling สำหรับ 401 และ 422
- เพิ่ม test สำหรับ update success และ validation error

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

Composer 2.5 รองรับ MCP หรือไม่?

รองรับ Composer 2.5 สามารถใช้ tool ของ Cursor รวมถึง MCP server ได้ เลือกโมเดลใน Cursor แล้วกำหนดค่า MCP server ในโปรเจกต์ ดูรายละเอียดการเลือกโมเดลได้ใน คู่มือ Composer 2.5

จำเป็นต้องใช้ Apidog เพื่อใช้ MCP กับ Composer 2.5 หรือไม่?

คุณต้องมีแหล่ง API specification แบบมีโครงสร้าง บทความนี้ใช้ Apidog MCP server เพราะรวม specification, testing และ mock ไว้ใน workflow เดียวกัน ตัวเลือกอื่นดูได้จาก รายการ MCP server สำหรับ Cursor

การผูกโมเดลกับ API specification จะหยุด hallucination ทั้งหมดหรือไม่?

ไม่ทั้งหมด แต่ช่วยลดข้อผิดพลาดใหญ่ ๆ เช่น endpoint ผิด, schema ผิด และ field ที่ไม่มีอยู่จริง เพราะโมเดลอ่าน contract แทนการเดา อย่างไรก็ตามยังต้องทดสอบกับ service จริงเสมอ

คุ้มไหมสำหรับโปรเจกต์ขนาดเล็ก?

คุ้มถ้าโมเดลต้องแตะ API จริง การตั้งค่า MCP เป็นงานครั้งเดียว แต่ช่วยให้ request ที่โมเดลสร้างหลังจากนั้นอ้างอิง contract เดียวกับทีม

สรุป

Composer 2.5 เร็วพอสำหรับงาน API จริง แต่จะมีประโยชน์ก็ต่อเมื่อมันเขียนโค้ดจาก API contract จริง ไม่ใช่เดาจาก pattern ทั่วไป เชื่อม API specification ผ่าน Apidog MCP server เพื่อให้ Composer 2.5 อ่าน endpoint, schema และ error response ที่ถูกต้อง จากนั้นใช้ Apidog ยิง request จริง ตรวจสอบ response และบันทึก case ที่ถูกต้องเป็น automated test หรือ mock

เวิร์กโฟลว์ที่ปลอดภัยคือ: generate จาก contract จริง → test กับ server จริง → บันทึกเป็น test case นี่คือวิธีเปลี่ยนความเร็วของ agent ให้เป็นโค้ดที่พร้อมใช้งานจริง

DEV Community