Chỉnh sửa đặc tả API thủ công rất dễ phát sinh lỗi: đổi tên một trường, thêm giá trị enum hoặc siết chặt trường bắt buộc đều có thể làm hỏng các endpoint đang tham chiếu đến lược đồ đó. Với Apidog CLI, bạn có thể để tác nhân AI thực hiện các thay đổi này theo quy trình có kiểm soát: xác thực trước khi ghi, làm việc trên nhánh biệt lập và chỉ hợp nhất sau khi được xem xét.
Bài viết này tập trung vào việc để tác nhân cập nhật đặc tả API một cách an toàn. Nếu bạn cần tạo tài liệu API bằng tác nhân, xem thêm hướng dẫn tạo tài liệu API bằng Apidog CLI.
“Cập nhật đặc tả” trong Apidog CLI là gì?
Trong Apidog, đặc tả API gồm endpoint và schema trong một dự án. Tác nhân thường sẽ dùng một trong ba nhóm lệnh:
-
endpoint update: cập nhật đường dẫn, tham số hoặc phản hồi của endpoint. -
schema update: cập nhật mô hình dữ liệu đang được endpoint tham chiếu. -
import: nhập một tệp OpenAPI mới để đồng bộ với dự án.
Trước khi tự động hóa các lệnh này, cần hiểu hai nguyên tắc: update là thao tác thay thế toàn bộ và thay đổi phải được cô lập trên nhánh AI.
Quy tắc quan trọng nhất: update thay thế toàn bộ đối tượng
Các lệnh update không hoạt động như JSON Patch. CLI gửi các trường bạn cung cấp và không tự hợp nhất các phần tử mảng theo ID.
Ví dụ: nếu bạn chỉ gửi một phần mảng parameters để sửa một tham số, phần còn lại của mảng có thể bị thay thế và biến mất.
Luôn yêu cầu tác nhân dùng quy trình đọc → sửa đổi → xác thực → ghi trên đối tượng đầy đủ:
# 1. Lấy toàn bộ endpoint hiện tại
apidog endpoint get <endpointId> --project <projectId>
# 2. Chỉnh sửa toàn bộ cấu trúc cục bộ
# Giữ nguyên mọi trường không cần thay đổi.
# 3. Lấy schema CLI và xác thực payload
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
Đưa quy tắc này vào prompt hoặc hướng dẫn hệ thống của tác nhân:
Không bao giờ gửi payload một phần cho lệnh update.
Luôn lấy toàn bộ tài nguyên hiện tại, sửa đổi đầy đủ đối tượng,
xác thực bằng cli-schema validate, rồi mới gọi update.
Bước get tránh mất trường ngoài ý muốn. Bước cli-schema validate giúp phát hiện payload sai trước khi tác nhân thay đổi dữ liệu trong dự án.
Làm việc an toàn trên nhánh AI
Không nên cấp cho tác nhân quyền sửa trực tiếp nhánh chính khi mới triển khai. Thay vào đó, dùng nhánh AI để cô lập thay đổi.
Quy trình này tương tự pull request:
- Tạo nhánh AI từ nhánh nguồn.
- Đưa các tài nguyên hiện có vào nhánh AI.
- Để tác nhân cập nhật trên nhánh AI.
- Xem xét diff và hợp nhất khi đã chấp thuậ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"
Nên dùng quy ước tên:
ai/YYYYMMDD-from-source-feature
Ví dụ:
ai/20260713-from-main-refund-fields
--from nên trỏ đến nhánh chính hoặc nhánh sprint thông thường, không phải nhánh chung. Nhánh AI không có thay đổi so với nguồn sẽ tự động được lưu trữ sau 24 giờ.
Bước 2: Đưa tài nguyên hiện có vào nhánh AI
Nhánh AI khởi tạo ở trạng thái trống, không tự sao chép endpoint hoặc schema từ nhánh nguồn. Trước khi chỉnh sửa tài nguyên hiện có, dùng pick-to:
apidog branch pick-to --project <projectId> --type ai \
--from main \
--to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Chỉ cần làm bước này với tài nguyên đã tồn tại mà tác nhân sẽ sửa hoặc xóa. Tài nguyên mới được tạo trực tiếp trên nhánh AI không cần pick-to.
Bước 3: Cập nhật trên nhánh AI
Thêm --branch vào các lệnh đọc và ghi để đảm bảo tác nhân chỉ thao tác trong phạm vi nhánh AI:
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 không bị ảnh hưởng trong giai đoạn này. Nếu tác nhân tạo thay đổi sai, bạn chỉ cần bỏ nhánh AI.
Bước 4: Xem xét và hợp nhất
Sau khi tác nhân hoàn thành, xem xét thay đổi trước khi đưa vào main.
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" \
--to main \
--endpoint-ids <ids>
Nếu nhánh chính được bảo vệ, ưu tiên tạo merge-request và phê duyệt trong ứng dụng Apidog. Lệnh branch merge sẽ ghi thay đổi trực tiếp và yêu cầu quyền chỉnh sửa trực tiếp trên cả nhánh nguồn lẫn nhánh đích.
Ví dụ: đổi tên trường amount thành amountCents
Giả sử schema Refund hiện có trường amount, và bạn muốn đổi tên thành amountCents đồng thời chuyển kiểu dữ liệu sang số nguyên.
Trước hết, lấy schema đầy đủ trên nhánh AI:
apidog schema get <refundSchemaId> \
--project $PID \
--branch "ai/20260713-from-main-refund-fields"
Tác nhân cần giữ nguyên toàn bộ schema, chỉ thay đổi trường cần thiết:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Điểm quan trọng: payload vẫn giữ orderId và reason. Không gửi riêng amountCents, vì update là thao tác thay thế.
Xác thực rồi cập nhật schema:
# 1. Xác thực payload hoàn chỉnh
apidog cli-schema validate schema-create --file ./refund-full.json
# 2. Cập nhật trên nhánh AI
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" \
--file ./refund-full.json
Sau đó, kiểm tra diff trên nhánh AI. Nếu chỉ có một trường được đổi tên và không có thay đổi ngoài ý muốn, tạo yêu cầu hợp nhất.
Bắt buộc phân loại thay đổi gây phá vỡ
Đổi tên trường bắt buộc là thay đổi gây phá vỡ. Client vẫn gửi amount sẽ không còn hợp lệ khi schema yêu cầu amountCents.
Đặt quy tắc rõ ràng cho tác nhân trước khi hợp nhất:
Trước khi hợp nhất bất kỳ thay đổi đặc tả nào, hãy phân loại thay đổi:
- Không phá vỡ:
trường tùy chọn mới, endpoint mới, ràng buộc được nới lỏng.
→ Tóm tắt thay đổi và tiếp tục tạo yêu cầu hợp nhất.
- Phá vỡ:
trường bị đổi tên hoặc xóa, trường bắt buộc mới, kiểu dữ liệu bị siết chặt.
→ DỪNG LẠI.
Báo cáo thay đổi gây phá vỡ, endpoint bị ảnh hưởng
và chờ phê duyệt rõ ràng từ con người.
Nhánh AI làm cho điểm kiểm tra này thực sự an toàn: thay đổi chưa được đưa vào nhánh chính cho đến khi có người phê duyệt.
Đồng bộ từ tệp OpenAPI
Nếu nguồn thay đổi đã tồn tại dưới dạng OpenAPI, chẳng hạn được sinh từ code hoặc do nhóm khác cung cấp, dùng import thay vì cập nhật từng trường:
apidog import --project <projectId> \
--format openapi \
--file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
import hỗ trợ OpenAPI 3.x, Swagger 2.0, Postman và các định dạng khác. Hãy luôn import vào nhánh AI trước để kiểm tra thay đổi trước khi hợp nhất vào nhánh chính.
Sau khi hợp nhất, xuất lại đặc tả để xác nhận kết quả:
apidog export --project <projectId> \
--format openapi \
--oas-version 3.1 \
--output ./openapi.json
Chọn cách làm phù hợp với nguồn chân lý:
- Dùng
importkhi OpenAPI bên ngoài là nguồn chân lý. - Dùng
endpoint updatehoặcschema updatekhi Apidog là nguồn chân lý và bạn chỉ cần thay đổi có chọn lọc.
Hoàn tác khi tác nhân làm sai
Nếu thay đổi trên nhánh AI không đạt yêu cầu, không cần sửa trực tiếp nhánh chính. Chỉ cần lưu trữ nhánh:
apidog branch archive "ai/20260713-from-main-refund-fields" \
--project <projectId> \
--type ai
Đó là lợi ích chính của nhánh AI: sai sót chỉ tồn tại trong một nhánh dùng một lần. Không cần khôi phục thủ công một thay đổi đã ghi trực tiếp vào main.
Lưu ý về quyền chỉnh sửa
Nếu update hoặc import bị chặn, dự án có thể đang tắt Quyền Chỉnh sửa AI Bên ngoài.
Quy trình nhánh AI là lựa chọn an toàn cho trường hợp này: tác nhân làm việc trên nhánh biệt lập, còn con người phê duyệt hợp nhất.
Nếu cần cấp quyền chỉnh sửa trực tiếp, thiết lập nằm tại:
Cài đặt Dự án
→ Cài đặt Tính năng
→ Cài đặt Tính năng AI
Thiết lập này yêu cầu Apidog client phiên bản 2.8.32+. Khi gặp rào cản quyền hạn, tác nhân nên báo cáo và chờ quyết định thay vì tự tìm cách обход qua cơ chế kiểm soát.
Các lỗi thường gặp
Gửi payload cập nhật một phần
updatethay thế thay vì hợp nhất. Luôn lấy đối tượng đầy đủ, sửa đổi, xác thực rồi ghi lại.Quên
pick-totài nguyên vào nhánh AI
Nhánh AI bắt đầu trống. Tác nhân không thể chỉnh sửa endpoint hoặc schema hiện có nếu tài nguyên chưa được đưa vào nhánh.Dùng sai nhánh nguồn trong
branch create
--fromphải là nhánh chính hoặc nhánh sprint, không phải nhánh chung.Bỏ qua
cli-schema validate
Xác thực cục bộ giúp phát hiện payload sai định dạng trước khi gọi API.Hợp nhất thay đổi gây phá vỡ mà không báo cáo
Bắt buộc tác nhân phân loại thay đổi và dừng lại khi phát hiện đổi tên/xóa trường, thêm trường bắt buộc hoặc siết kiểu dữ liệu.
Câu hỏi thường gặp
Có thể để tác nhân chỉnh sửa trực tiếp nhánh chính không?
Có, nếu bật Quyền Chỉnh sửa AI Bên ngoài. Tuy nhiên, nên bắt đầu với nhánh AI để mọi thay đổi đều được xem xét trước khi vào nhánh chính.
branch merge khác gì merge-request?
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 tạo yêu cầu để xem xét, phù hợp khi nhánh chính được bảo vệ.
Tác nhân có cần cài ứng dụng Apidog trên máy không?
Không. CLI hoạt động độc lập. Ứng dụng chỉ cần thiết khi bạn cấu hình Quyền Chỉnh sửa AI Bên ngoài.
Làm sao để tránh tác nhân tự bịa tên trường?
Bắt buộc tác nhân dùng chuỗi lệnh:
cli-schema get → cli-schema validate → update
Payload chứa trường không hợp lệ sẽ không vượt qua bước xác thực cục bộ.
Tổng kết
Để tác nhân AI cập nhật đặc tả API an toàn, hãy áp dụng ba điều kiện:
- Làm việc trên nhánh AI biệt lập.
- Luôn dùng quy trình đọc → sửa đổi → xác thực → ghi với đối tượng đầy đủ.
- Yêu cầu con người xem xét trước khi hợp nhất, đặc biệt với thay đổi gây phá vỡ.
Thiết lập nhánh AI, thêm quy tắc chống cập nhật một phần và yêu cầu báo cáo breaking changes. Khi đó, bảo trì API spec trở thành một diff có thể xem xét thay vì một thao tác thủ công đầy rủi ro.
Tải Apidog để sử dụng CLI, đồng thời kết hợp với hướng dẫn để tác nhân tạo tài liệu API để tự động hóa cả quy trình tạo và duy trì tài liệu.
Top comments (0)