Chỉnh sửa đặc tả API bằng tay là một công việc tỉ mỉ, phức tạp. Đổi tên một trường, thêm giá trị enum, thắt chặt một cờ bắt buộc. Mỗi thay đổi đều nhỏ, nhưng mỗi thay đổi đó phải được đặt đúng chỗ mà không làm hỏng các điểm cuối tham chiếu đến nó. Đó là công việc chính xác, máy móc và chính xác là loại nhiệm vụ bạn sẽ giao cho một tác nhân AI, nếu bạn có thể tin tưởng nó không phá hỏng toàn bộ lược đồ.
Bạn có thể. CLI của Apidog cung cấp cho tác nhân mọi thứ cần thiết để thay đổi đặc tả một cách có trách nhiệm: xác thực lược đồ trước mỗi lần ghi, một nhánh biệt lập để làm việc và một yêu cầu hợp nhất để bạn xem xét.
nút
Đây là bản hướng dẫn về thay đổi đi kèm với việc để tác nhân tạo tài liệu API. Việc tạo là bổ sung và có rủi ro thấp; cập nhật một hợp đồng hiện có là nơi các biện pháp bảo vệ quan trọng, vì vậy phần lớn hướng dẫn này là về cách thực hiện mà không làm hỏng bất cứ điều gì.
Ý nghĩa của “cập nhật đặc tả” trong CLI
Đặc tả của bạn trong Apidog là tập hợp các điểm cuối và lược đồ dữ liệu trong một dự án. Việc cập nhật nó có nghĩa là một trong ba lệnh sau:
endpoint update: thay đổi một đường dẫn, một tham số, một phản hồi.schema update: thay đổi một mô hình dữ liệu mà các điểm cuối tham chiếu.import: nhập toàn bộ tệp OpenAPI mới để đối chiếu với dự án.
Trước khi bạn hướng tác nhân vào bất kỳ lệnh nào trong số này, có hai hành vi bạn phải hiểu, bởi vì làm sai chúng là cách một đặc tả bị hỏng. Đầu tiên là mô hình quyền, và thứ hai là một lỗi khó nhận biết có thể âm thầm xóa dữ liệu.
Cạm bẫy sẽ làm bạn mắc lỗi: cập nhật là thay thế hoàn toàn
Đây là điều quan trọng nhất để dạy tác nhân của bạn. Các lệnh `update` của CLI **không phải** là JSON Patch. Chúng gửi trực tiếp các trường bạn cung cấp; chúng không hợp nhất các mục mảng theo ID. Nếu bạn gửi một bản cập nhật với một mảng `parameters` một phần với ý định thay đổi một tham số, bạn không chỉnh sửa tham số đó. Bạn thay thế toàn bộ mảng chỉ bằng cái bạn đã gửi, và phần còn lại sẽ biến mất.
Trình tự đúng luôn là đọc-sửa đổi-ghi trên đối tượng *hoàn chỉnh*:
# 1. Lấy tài nguyên hiện tại đầy đủ
apidog endpoint get <endpointId> --project <projectId>
# 2. Chỉnh sửa cấu trúc hoàn chỉnh cục bộ (giữ lại mọi trường bạn không thay đổi)
# 3. Xác thực toàn bộ đối tượng với lược đồ
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Ghi lại đối tượng hoàn chỉnh
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Hãy đưa điều này vào hướng dẫn của tác nhân một cách rõ ràng: *không bao giờ gửi một đối tượng một phần để `update`; luôn luôn lấy toàn bộ tài nguyên, sửa đổi nó và gửi lại toàn bộ.* Một tác nhân bỏ qua bước `get` sẽ âm thầm loại bỏ các trường. Một tác nhân chạy `cli-schema validate` trước sẽ bắt được lỗi của chính nó trước khi chúng đến dự án.
Con đường an toàn: để tác nhân làm việc trên một nhánh AI
Bạn có thể cấp cho tác nhân quyền chỉnh sửa trực tiếp trên nhánh chính của mình. Đừng làm vậy, ít nhất là lúc đầu. Apidog có một cơ chế cách ly được xây dựng có chủ đích, đó là **nhánh AI**, được thiết kế chính xác cho điều này: một tác nhân sửa đổi tài nguyên mà không chạm vào nhánh nguồn, và không có gì được hợp nhất trở lại cho đến khi bạn cho phép. Hãy coi nó như một yêu cầu kéo (pull request) cho đặc tả API của bạn.
Bước 1: Tạo nhánh AI
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
Quy ước đặt tên là `ai/YYYYMMDD-from-source-feature` để nguồn gốc và mục đích của nhánh dễ hiểu ngay từ cái nhìn đầu tiên. Giá trị `--from` phải là nhánh chính của bạn hoặc một nhánh sprint thông thường, không phải là một nhánh chung. Một chi tiết tiện lợi: một nhánh AI không có sự khác biệt nào so với nguồn của nó sẽ tự động được lưu trữ sau 24 giờ, vì vậy các thử nghiệm bị bỏ dở sẽ tự dọn dẹp.
Bước 2: Nhập các tài nguyên mà tác nhân sẽ chỉnh sửa
Một nhánh AI bắt đầu trống. Nó không tự động sao chép nhánh nguồn. Trước khi tác nhân có thể chỉnh sửa một điểm cuối hoặc lược đồ *hiện có*, hãy kéo tài nguyên đó vào nhánh bằng `pick-to`:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Các tài nguyên mà tác nhân *tạo* mới trên nhánh không cần điều này; chỉ những tài nguyên hiện có mà nó định sửa đổi hoặc xóa. Đây là bước mà mọi người thường quên: bỏ qua nó, và tác nhân sẽ có một nhánh trống rỗng và không có gì để chỉnh sửa.
Bước 3: Để tác nhân thực hiện thay đổi
Bây giờ tác nhân chạy vòng lặp đọc-sửa đổi-ghi từ trước, nhưng với `--branch` trỏ đến nhánh AI. Mọi chỉnh sửa được gói gọn:
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
Nhánh chính của bạn không bị chạm đến trong suốt thời gian này. Nếu tác nhân làm sai điều gì đó, phạm vi ảnh hưởng chỉ là một nhánh dùng một lần.
Bước 4: Xem xét, sau đó hợp nhất
Các thay đổi trên nhánh AI không bao giờ được ghi lại tự động. Khi tác nhân hoàn thành, *bạn* quyết định điều gì sẽ xảy ra. Nếu mục tiêu được bảo vệ, hãy mở một yêu cầu hợp nhất thay vì hợp nhất trực tiếp:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Xem xét sự khác biệt, phê duyệt, và thay đổi đã được kiểm tra sẽ xuất hiện trên nhánh chính. Hợp nhất trực tiếp từ CLI yêu cầu quyền chỉnh sửa trực tiếp trên cả nhánh nguồn và nhánh đích; nếu nhánh chính được bảo vệ, hãy ưu tiên `merge-request` và phê duyệt nó trong ứng dụng Apidog.
Một ví dụ thực tế: đổi tên một trường an toàn
Các quy tắc trừu tượng thì dễ gật đầu đồng ý nhưng khó áp dụng. Đây là một ví dụ cụ thể. Giả sử bạn muốn đổi tên `amount` thành `amountCents` trên mô hình dữ liệu `Refund`, bởi vì bạn đang chuyển sang sử dụng số tiền là số nguyên (cent).
Bạn nói với tác nhân: *“Đổi tên trường `amount` trên lược đồ Refund thành `amountCents` và biến nó thành một số nguyên.”* Theo các quy tắc của nó, tác nhân sẽ:
# 1. Lấy lược đồ HIỆN TẠI ĐẦY ĐỦ trên nhánh AI
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Nó nhận lại đối tượng hoàn chỉnh và chỉnh sửa toàn bộ `jsonSchema`, giữ nguyên mọi trường mà nó không chạm vào:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Lưu ý điều *không* xảy ra: nó không chỉ gửi một thuộc tính đã thay đổi. Nó đã gửi toàn bộ lược đồ với `orderId` và `reason` còn nguyên vẹn, bởi vì `update` thực hiện thay thế. Sau đó:
# 2. Xác thực đối tượng hoàn chỉnh
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Ghi nó trở lại nhánh AI
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Bạn xem xét sự khác biệt trên nhánh AI (một trường được đổi tên, không có gì khác bị xáo trộn) và hợp nhất. Đó là toàn bộ quy trình: đối tượng đầy đủ, được xác thực, trên một nhánh, hợp nhất sau khi xem xét.
Đánh dấu các thay đổi gây phá vỡ trước khi hợp nhất
Đổi tên một trường bắt buộc là một thay đổi gây phá vỡ: bất kỳ client nào gửi `amount` giờ đây sẽ thất bại trong việc xác thực. Một bộ hướng dẫn tốt cho tác nhân sẽ khiến mô hình *nói ra* điều đó thay vì hợp nhất một cách im lặng. Thêm điều này vào các quy tắc của tác nhân:
Trước khi hợp nhất bất kỳ thay đổi đặc tả nào, hãy phân loại nó:
- Không phá vỡ (trường tùy chọn mới, điểm cuối mới, ràng buộc nới lỏng) → tóm tắt và tiếp tục với yêu cầu hợp nhất.
- Phá vỡ (trường đổi tên/bị xóa, trường bắt buộc mới, kiểu thắt chặt) → DỪNG LẠI.
Báo cáo thay đổi gây phá vỡ và các điểm cuối bị ảnh hưởng, và đợi sự chấp thuận rõ ràng của con người.
Nhánh AI là điều làm cho việc thực thi điều này an toàn: bởi vì không có gì tự động hợp nhất, “dừng lại và báo cáo” là một điểm kiểm tra thực sự, không phải là một cuộc chạy đua chống lại một thao tác ghi đã xảy ra.
Thay vào đó, cập nhật từ một tệp OpenAPI
Đôi khi thay đổi đã tồn tại dưới dạng tệp OpenAPI, được tạo từ mã, chỉnh sửa ở nơi khác hoặc được một nhóm khác chuyển giao cho bạn. Thay vì thực hiện lại từng chỉnh sửa theo trường, tác nhân có thể nhập tệp để đối chiếu nó với dự án:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
`import` chấp nhận OpenAPI 3.x, Swagger 2.0, Postman và nhiều định dạng khác. Hãy chạy nó trên một nhánh AI trước để bạn có thể xem xét những thay đổi của đặc tả sắp tới trước khi nó đến nhánh chính. Sau khi hợp nhất, xuất lại đặc tả đã đối chiếu để xác nhận kết quả:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Cách này tốt nhất khi nguồn chân lý nằm ngoài Apidog và bạn đang đồng bộ hóa nó vào. Cách `update` từng trường tốt nhất khi Apidog *là* nguồn chân lý và bạn đang thực hiện một thay đổi có chọn lọc.
Khi tác nhân làm sai: hoàn tác
Lý do để làm việc trên một nhánh AI là lỗi lầm dễ dàng được hoàn tác. Nếu tác nhân tạo ra một thay đổi mà bạn không muốn, bạn chưa bao giờ hợp nhất nó, vì vậy nhánh chính vẫn đúng. Chỉ cần lưu trữ nhánh và tiếp tục:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Bởi vì một nhánh AI không có sự khác biệt nào được chấp nhận dù sao cũng tự động lưu trữ sau 24 giờ, ngay cả một thử nghiệm bị quên lãng cũng tự dọn dẹp. So sánh điều đó với một tác nhân chỉnh sửa trực tiếp nhánh chính, trong đó một `update` tồi tệ sẽ có hiệu lực ngay lập tức và giải pháp duy nhất của bạn là thùng rác hoặc hoàn tác thủ công. Nhánh không phải là sự quan liêu; nó là nút hoàn tác.
Một lưu ý về quyền hạn
Nếu một lệnh `update` hoặc `import` bị chặn, dự án đã tắt Quyền Chỉnh sửa AI Bên ngoài. Đó là một cổng kiểm soát có chủ ý, và quy trình nhánh AI ở trên là câu trả lời cho điều đó: tác nhân chỉnh sửa một nhánh biệt lập và bạn phê duyệt việc hợp nhất. Nếu bạn muốn cấp quyền chỉnh sửa trực tiếp, công tắc nằm trong Cài đặt Dự án → Cài đặt Tính năng → Cài đặt Tính năng AI (phiên bản Apidog client 2.8.32+). Khi một tác nhân gặp phải rào cản quyền hạn, đừng để nó âm thầm chọn một cách giải quyết; hãy đưa ra lựa chọn đó cho một con người.
Những vướng mắc thường gặp
- Cập nhật một phần xóa mất các trường. Lỗi gây hại nhất và phổ biến nhất. `update` thay thế; nó không hợp nhất. Lấy toàn bộ đối tượng, chỉnh sửa toàn bộ, xác thực, sau đó ghi. Nếu một trường biến mất, tác nhân đã gửi một tải trọng không đầy đủ.
- Chỉnh sửa một tài nguyên hiện có trên nhánh AI mà không nhập nó. Nhánh bắt đầu trống. Hãy `pick-to` tài nguyên vào trước, nếu không tác nhân sẽ không có gì để chỉnh sửa.
- Sai `--from` cho nhánh AI. Nguồn phải là nhánh chính hoặc nhánh sprint, không bao giờ là nhánh chung. Lệnh `branch create` sẽ báo lỗi nếu bạn làm sai.
- Bỏ qua xác thực. `cli-schema validate` bắt được một tải trọng không đúng định dạng trên máy của bạn. Một tác nhân ghi mà không xác thực sẽ biến một lỗi đánh máy thành một cuộc gọi API thất bại, hoặc tệ hơn, một hợp nhất không tốt.
- Hợp nhất một thay đổi gây phá vỡ một cách âm thầm. Nếu không có quy tắc phân loại trước, tác nhân sẽ vui vẻ đổi tên một trường bắt buộc và hợp nhất nó. Hãy biến việc phát hiện thay đổi gây phá vỡ thành một điểm kiểm tra rõ ràng.
Câu hỏi thường gặp
- Tôi có thể để tác nhân chỉnh sửa trực tiếp nhánh chính không? Bạn có thể, bằng cách bật Quyền Chỉnh sửa AI Bên ngoài, nhưng bắt đầu trên một nhánh AI an toàn hơn: không có gì xuất hiện trên nhánh chính cho đến khi bạn phê duyệt một hợp nhất. Hãy dành việc chỉnh sửa trực tiếp cho các tác vụ tự động hóa có rủi ro thấp, độ tin cậy cao.
- Sự khác biệt giữa `branch merge` và `merge-request` là gì? `branch merge` ghi thay đổi ngay lập tức và cần quyền chỉnh sửa trực tiếp trên cả hai nhánh. `merge-request` mở một yêu cầu có thể xem xét, đây là lựa chọn đúng đắn khi nhánh chính được bảo vệ.
- Tác nhân có cần ứng dụng Apidog trên máy tính không? Không, CLI hoạt động độc lập. Ứng dụng chỉ quan trọng để bật/tắt cài đặt Quyền Chỉnh sửa AI Bên ngoài, đây là một cấu hình một lần.
- Làm cách nào để đảm bảo tác nhân không bịa đặt tên trường? Vòng lặp `cli-schema get` → `validate` là biện pháp bảo vệ. Một tải trọng với một trường bịa đặt sẽ không vượt qua xác thực cục bộ, trước khi nó đến dự án.
Tổng kết
Để tác nhân cập nhật đặc tả API của bạn là an toàn khi ba điều sau đúng: nó hoạt động trên một nhánh AI biệt lập, nó coi mỗi bản cập nhật là một thao tác đọc-sửa đổi-ghi hoàn chỉnh thay vì một bản vá, và một con người phê duyệt việc hợp nhất. CLI của Apidog cung cấp cho bạn cả ba điều này dưới dạng lệnh, có nghĩa là toàn bộ vòng lặp (chỉnh sửa, xác thực, xem xét) có thể được lập trình và kiểm tra, và một thay đổi không tốt chỉ cần một lệnh `archive` là biến mất.
Thiết lập nhánh AI, giao cho tác nhân quy tắc đọc-sửa đổi-ghi và điểm kiểm tra thay đổi gây phá vỡ, và việc bảo trì đặc tả trở thành một sự khác biệt mà bạn phê duyệt thay vì công việc tỉ mỉ mà bạn cứ trì hoãn. Tải Apidog để có CLI, và kết hợp điều này với việc để tác nhân tạo tài liệu của bạn để bao quát toàn bộ vòng lặp tạo và bảo trì.