Sebastian Petrus

Posted on May 19 • Originally published at apidog.com

Cách xây dựng API với Cursor Composer 2.5

Cursor Composer 2.5 đủ nhanh và rẻ để một tác nhân có thể viết client API và kết nối luồng xử lý cho bạn. Nhưng nếu mô hình không đọc hợp đồng API thực tế, nó có thể tạo request tới /v2/orders trong khi service của bạn chỉ có /orders, hoặc dùng payload sai. Code vẫn compile, nhưng lỗi chỉ lộ ra khi chạy với backend thật.

Thử Apidog ngay hôm nay

Bài viết này hướng dẫn workflow thực tế: kết nối Composer 2.5 với spec API thật thông qua MCP, để nó sinh code theo hợp đồng hiện có, rồi xác minh request trong Apidog trước khi gửi cho team. Nếu bạn mới dùng mô hình này, xem thêm hướng dẫn về Cursor Composer 2.5.

Vì sao mô hình tác nhân hay đoán sai API

Composer 2.5 được thiết kế cho tác vụ tác nhân dài, nhiều bước. Bạn có thể yêu cầu:

“Thêm client cho service thanh toán và kết nối nó vào luồng checkout.”

Mô hình sẽ lập kế hoạch, chỉnh sửa nhiều file và chạy test. Đây là nâng cấp hữu ích so với Composer 2.

Vấn đề là: nếu spec API không nằm trong ngữ cảnh, mô hình sẽ tự suy luận dựa trên các pattern phổ biến:

Endpoint gần đúng: /api/users/{id} thay vì /users/{userId}
Body request có field thừa, thiếu hoặc sai tên
Auth được xử lý theo kiểu chung chung thay vì theo schema thật
Error response được giả định thay vì đọc từ spec

Prompt có thể giảm lỗi, nhưng dán toàn bộ OpenAPI vào chat không ổn định và tốn context. Cách bền vững hơn là cho mô hình truy cập spec qua một nguồn có cấu trúc.

Giải pháp: cho Composer 2.5 đọc spec API qua MCP

Model Context Protocol, hay MCP, là chuẩn mở để cung cấp tool và dữ liệu cho mô hình AI. Cursor hỗ trợ MCP server. Apidog MCP server expose spec API trong Apidog dưới dạng nguồn có cấu trúc để Composer có thể truy vấn khi viết code.

Thay vì đoán endpoint, parameter, schema và response, Composer 2.5 có thể đọc chúng từ hợp đồng thật. Đây cũng là ý tưởng trong vibe coding với Apidog MCP server, nhưng áp dụng cho workflow triển khai tính năng hoàn chỉnh.

Bước 1: Chuẩn bị spec API trong Apidog

Trước tiên, đảm bảo API contract của bạn nằm trong Apidog và được cập nhật.

Bạn có thể:

Thiết kế API trực tiếp trong Apidog.
Import OpenAPI spec hiện có.
Import Postman collection.
Bổ sung request body, response schema, auth, header và ví dụ.

Spec này sẽ là nguồn chân lý cho Composer 2.5. Nếu spec sai hoặc lỗi thời, mô hình vẫn có thể sinh code sai theo đúng thông tin sai đó.

Bước 2: Kết nối Apidog MCP server với Cursor

Cursor đọc MCP server từ file cấu hình trong project, thường là:

.cursor/mcp.json

Một cấu hình điển hình:

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

Thay các giá trị sau bằng thông tin thật:

<your-project-id>: ID project Apidog
<your-access-token>: access token của bạn
package/version server: dùng đúng theo hướng dẫn cài đặt Apidog MCP

Sau khi lưu file, khởi động lại Cursor để nhận MCP server mới.

Bước 3: Kiểm tra Composer 2.5 có đọc được spec không

Mở một phiên agent trong Cursor, chọn composer-2.5, rồi hỏi một câu chỉ đọc:

Sử dụng MCP server apidog-api-spec, liệt kê các endpoint thuộc resource orders và các field bắt buộc để tạo order.

Nếu Composer trả về endpoint, parameter và field đúng với project của bạn, kết nối đã hoạt động.

Nếu nó trả lời chung chung kiểu REST phổ biến, hãy kiểm tra lại:

File .cursor/mcp.json
Tên MCP server
Project ID
Access token
Cursor đã được restart chưa

Bước 4: Yêu cầu Composer sinh code theo hợp đồng

Khi MCP đã hoạt động, prompt nên chỉ rõ nguồn spec:

Sử dụng MCP server apidog-api-spec làm nguồn chân lý.

Viết một TypeScript client được định kiểu cho Orders API, bao gồm:
- createOrder
- getOrder

Yêu cầu:
- Khớp chính xác request schema và response schema trong spec
- Dùng đúng endpoint và HTTP method
- Thêm xử lý lỗi cho response validation 422 mà spec định nghĩa
- Không tự tạo field ngoài spec

Ví dụ output mong muốn có thể là một client dạng:

type CreateOrderRequest = {
  customerId: string;
  items: Array<{
    productId: string;
    quantity: number;
  }>;
};

type OrderResponse = {
  id: string;
  status: string;
  createdAt: string;
};

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

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

  if (!res.ok) {
    throw new Error(`Failed to create order: ${res.status}`);
  }

  return res.json();
}

Tên field, endpoint và error shape trong code thực tế phải đến từ spec của bạn, không phải từ ví dụ trên.

Xác minh trước khi tin: vòng lặp kiểm thử với Apidog

Cho mô hình đọc spec giúp giảm mạnh lỗi ảo giác, nhưng không thay thế kiểm thử. Spec có thể lệch so với service đang chạy, hoặc mô hình có thể xử lý sai một edge case.

Workflow nên là:

Sinh code từ spec
- Composer 2.5 đọc API contract qua MCP.
- Code được tạo theo endpoint, schema, auth và response thật.
Chạy request thật trong Apidog
- Lấy endpoint mà Composer dùng.
- Gửi request trong Apidog.
- Kiểm tra status code, response body, validation và auth.
Lưu request thành test
- Với request đã chạy đúng, lưu thành test scenario.
- Đưa vào quy trình regression để lỗi được phát hiện trước khi tới người dùng.
Mock endpoint chưa triển khai
- Nếu backend chưa sẵn sàng, dùng mock server của Apidog.
- Frontend/client vẫn có response thực tế để phát triển tiếp.
- Cách này phù hợp với các pattern trong AI agents và kiểm thử API.

Nguyên tắc đơn giản: mô hình viết bản nháp đầu tiên dựa trên hợp đồng, còn bạn xác minh bản nháp đó với server thật hoặc mock đáng tin cậy.

Ví dụ workflow từ đầu đến cuối

Giả sử bạn đang thêm tính năng hoàn tiền cho service thanh toán.

1. Spec đã có trong Apidog

Trong project Apidog đã có:

Endpoint tạo refund
Request body
Response schema
Header idempotency-key
Error khi refund trùng lặp

2. Cursor đã kết nối Apidog MCP

Bạn có .cursor/mcp.json trỏ tới project Apidog và đã restart Cursor.

3. Prompt cho Composer 2.5

Sử dụng apidog-api-spec làm nguồn chân lý.

Xây dựng refund client và một React hook gọi client đó.

Yêu cầu:
- Tuân thủ chính xác schema trong spec
- Bao gồm header idempotency-key nếu spec yêu cầu
- Xử lý lỗi 409 khi refund bị trùng
- Thêm type cho request và response
- Chạy test hiện có sau khi chỉnh sửa

4. Composer sinh code

Composer có thể tạo:

refundClient.ts
TypeScript types
React hook như useCreateRefund
Test hoặc cập nhật test hiện có

5. Xác minh trong Apidog

Sau đó bạn mở Apidog và kiểm tra:

Request tạo refund thành công
Header idempotency-key được gửi đúng
Trường hợp trùng lặp trả về lỗi 409 như mong đợi
Response body khớp với code đã xử lý

Nếu mọi thứ đúng, lưu các request này thành test scenario.

Điều bạn tránh được là một client quên header idempotency, gây refund trùng trong staging. Đây là loại lỗi mà workflow “spec-driven generation + verification” xử lý tốt.

FAQ

Composer 2.5 có hỗ trợ MCP không?

Có. Composer 2.5 có thể dùng bộ công cụ agent của Cursor, bao gồm MCP server. Chọn composer-2.5 trong model picker và cấu hình MCP server trong project. Xem thêm hướng dẫn Composer 2.5.

Tôi có bắt buộc phải dùng Apidog để dùng MCP với Composer 2.5 không?

Bạn cần một nguồn spec có cấu trúc. Apidog MCP server là hướng được dùng trong bài này vì nó kết hợp spec, testing và mocking trong cùng một nơi. Ngoài ra vẫn có các lựa chọn khác trong danh sách MCP server tốt nhất cho Cursor.

Việc cho mô hình đọc spec có loại bỏ toàn bộ ảo giác không?

Không hoàn toàn. Nó loại bỏ nhóm lỗi lớn nhất: endpoint, schema và parameter bị đoán sai. Nhưng bạn vẫn cần kiểm thử vì spec có thể không khớp hoàn toàn với service đang chạy.

Dự án nhỏ có cần workflow này không?

Có, nếu mô hình đang viết code gọi API thật. Chi phí thiết lập chỉ là một file cấu hình, còn lợi ích là mỗi request được sinh ra dựa trên hợp đồng của bạn thay vì phỏng đoán.

Tổng kết

Composer 2.5 đủ mạnh để xử lý công việc API thực tế, nhưng chỉ đáng tin khi nó đọc hợp đồng thật. Kết nối spec qua Apidog MCP để Composer sinh code theo API contract, sau đó dùng Apidog để gửi request, xác minh response và lưu các case hoạt động thành test hoặc mock. Đây là workflow giúp biến tốc độ của agent thành tính năng có thể triển khai.

DEV Community