Tài liệu API luôn quan trọng, nhưng thường bị chậm hơn code: endpoint đã triển khai, tài liệu tham khảo chưa cập nhật; hướng dẫn bắt đầu vẫn mô tả luồng xác thực đã bị thay thế từ vài sprint trước. Đây là công việc lặp lại, dễ trì hoãn và phù hợp để tự động hóa bằng tác nhân AI.
Nếu tác nhân có thể chạy lệnh terminal, tác nhân có thể tạo endpoint, viết hướng dẫn Markdown và xuất bản trang tài liệu từ một yêu cầu ngôn ngữ tự nhiên. Apidog CLI cung cấp các lệnh có thể script cùng đầu ra JSON có cấu trúc để tác nhân đọc và quyết định bước tiếp theo.
Tại sao dùng CLI thay vì GUI hoặc máy chủ MCP?
Tác nhân có thể làm việc với tài liệu API theo ba cách, nhưng mỗi cách phục vụ một mục tiêu khác nhau.
| Phương pháp | Hướng | Ai điều khiển | Có thể xem sự khác biệt? |
|---|---|---|---|
| GUI | Chỉnh sửa trong trình duyệt | Con người, thao tác nhấp chuột | Không |
| Máy chủ MCP | Đọc đặc tả API → viết mã | Tác nhân trong trình soạn thảo | Trong kho mã, không phải tài liệu |
| CLI | Tạo và xuất bản tài liệu | Tác nhân trong terminal | Có, mọi lệnh đều được ghi lại |
Máy chủ MCP phù hợp khi bạn muốn tác nhân đọc định nghĩa API và tạo mã client. Ví dụ, luồng tài liệu MCP trong Cursor có thể dùng đặc tả API để hỗ trợ viết mã.
Trong bài này, mục tiêu là ngược lại: yêu cầu tác nhân tạo tài liệu — tạo endpoint, soạn hướng dẫn Markdown và xuất bản trang tài liệu.
CLI phù hợp hơn cho luồng này vì:
- Tính xác định: cùng một lệnh cho cùng một kết quả.
- Có thể script: dễ đưa vào CI/CD hoặc workflow của tác nhân.
-
Phản hồi JSON: mỗi lệnh trả về dữ liệu có cấu trúc, bao gồm
agentHints.nextStepsđể tác nhân biết bước tiếp theo.
Thay vì đoán workflow, tác nhân có thể tuân theo gợi ý trực tiếp từ CLI.
Thiết lập môi trường cho tác nhân
Cài đặt CLI và đăng nhập một lần:
npm install -g apidog-cli
apidog login --with-token <TOKEN>
Hướng dẫn cài đặt có thông tin về phiên bản Node và PATH. Hướng dẫn xác thực mô tả cách dùng token và bí mật CI.
Lấy token trong ứng dụng Apidog qua Avatar người dùng → Account Settings → API Access Token. Sau khi đăng nhập, token được lưu cục bộ nên tác nhân không phải truyền token trong mọi lệnh gọi.
Các thao tác ghi cần ID dự án. Bạn có thể tìm ID trong Project Settings → Basic Settings hoặc chạy:
apidog project list
Bất kỳ tác nhân nào có thể chạy shell đều dùng được: Claude Code, Cursor, Codex hoặc các coding agent tương tự.
Nghi thức ghi mà tác nhân phải tuân theo
Các lệnh tạo hoặc cập nhật tài liệu nhận payload từ tệp JSON. Không để tác nhân tự đoán cấu trúc JSON từ bộ nhớ.
Thay vào đó, luôn dùng quy trình bốn bước:
# 1. Lấy schema payload chính xác từ CLI
apidog cli-schema get doc-create
# 2. Tạo tệp JSON dựa trên schema đó
# 3. Xác thực cục bộ trước khi ghi
apidog cli-schema validate doc-create --file ./doc.json
# 4. Chỉ chạy thao tác ghi khi payload hợp lệ
apidog doc create --project <projectId> --file ./doc.json
Dán quy tắc sau vào system prompt, CLAUDE.md hoặc .cursorrules của tác nhân:
Quy tắc CLI của Apidog:
- Không bao giờ tự viết tay một payload JSON. Chạy `apidog cli-schema get <key>` trước và xây dựng từ schema đó.
- Xác thực mọi tệp với `apidog cli-schema validate <key> --file <path>` trước bất kỳ thao tác tạo hoặc cập nhật nào.
- Luôn truyền --project <id> trong các lệnh ghi.
- Đọc trường `agentHints.nextSteps` trong mỗi phản hồi JSON để chọn lệnh tiếp theo.
- Nếu một thao tác ghi bị chặn bởi quyền, hãy dừng lại và hỏi người dùng; không tự chọn giải pháp thay thế.
Quy trình này giúp chuyển lỗi từ giai đoạn ghi từ xa sang xác thực cục bộ. Tác nhân không còn gửi payload với trường tự đoán rồi chờ lỗi từ API.
Bước 1: Tạo tài liệu tham khảo từ endpoint và schema
Trong Apidog, tài liệu tham khảo API được tạo từ endpoint và schema dữ liệu trong dự án. Vì vậy, tác nhân cần tạo các tài nguyên này trước.
Ví dụ, bạn yêu cầu:
“Thêm endpoint
POST /refundsnhận ID đơn hàng và số tiền, đồng thời tài liệu hóa phản hồi thành công và lỗi xác thực.”
Tác nhân nên tạo schema dùng lại trước, sau đó tạo endpoint tham chiếu đến schema đó.
Đầu tiên, lấy schema cho thao tác tạo schema:
apidog cli-schema get schema-create
Sau đó tạo refund-schema.json:
{
"name": "Refund",
"description": "A refund issued against an order",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amount"],
"properties": {
"orderId": { "type": "string" },
"amount": { "type": "number" },
"reason": { "type": "string" }
}
}
}
Xác thực và tạo schema:
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Tiếp theo, lấy schema cho endpoint:
apidog cli-schema get endpoint-create
Tạo refunds-endpoint.json, sử dụng ID schema vừa tạo:
{
"name": "Create refund",
"method": "post",
"path": "/refunds",
"status": "developing",
"requestBody": {
"type": "application/json",
"jsonSchema": {
"$ref": "#/definitions/<refundSchemaId>"
}
}
}
Xác thực và tạo endpoint:
apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Tài liệu tham khảo cho /refunds hiện được tạo từ chính định nghĩa endpoint và schema mà nhóm của bạn quản lý. Không cần bước xuất tài liệu riêng cho phần API reference.
Điểm quan trọng là schema là nguồn ưu tiên duy nhất: tài liệu tham khảo không bị lệch khỏi API vì nó được tạo trực tiếp từ schema.
Bước 2: Viết hướng dẫn Markdown
Tài liệu tham khảo API không đủ để giúp người dùng bắt đầu. Bạn thường vẫn cần:
- Hướng dẫn bắt đầu nhanh
- Hướng dẫn xác thực
- Giải thích idempotency
- Ghi chú di chuyển
- Ví dụ tích hợp
Trong Apidog, các tài liệu này nằm trong cây tài liệu của dự án dưới dạng Markdown và được quản lý bằng nhóm lệnh doc.
Lấy schema tạo tài liệu:
apidog cli-schema get doc-create
Schema doc-create yêu cầu name; trường content chứa Markdown; folderId xác định vị trí trong cây tài liệu. Giá trị 0 là thư mục gốc.
Ví dụ quickstart.json:
{
"name": "Quickstart: Your first refund",
"content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
"folderId": 0
}
Kiểm tra tài liệu hiện có, xác thực payload và tạo tài liệu:
apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Bạn có thể giao cho tác nhân một yêu cầu như:
“Viết hướng dẫn nhanh giúp lập trình viên mới đi từ API key đến khoản hoàn tiền đầu tiên.”
Tác nhân sẽ soạn Markdown, đóng gói nội dung vào payload hợp lệ, xác thực rồi tạo tài liệu. Không cần mở trình duyệt hoặc sao chép-dán nội dung.
Bước 3: Xuất bản trang tài liệu
Sau khi có API reference và các hướng dẫn Markdown, tác nhân có thể xuất bản tài liệu từ terminal.
Ba khái niệm dễ nhầm lẫn:
-
doc: tài liệu Markdown trong cây API của dự án. -
docs-site: trang tài liệu công khai được lưu trữ. -
shared-doc: liên kết chia sẻ cho đối tác hoặc người nhận cụ thể, không phải toàn bộ website tài liệu.
Để tạo trang tài liệu công khai:
apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog cli-schema validate docs-site-create --file ./docs-site.json
apidog docs-site create --project <projectId> --file ./docs-site.json
Dùng docs-site khi cần trang web tài liệu công khai. Dùng shared-doc khi chỉ cần gửi một liên kết chia sẻ.
Vì đây đều là lệnh CLI, bạn có thể đưa bước xuất bản vào workflow sau mỗi lần thay đổi tài liệu.
Bước 4: Xuất bản bản sao di động
Nếu cần tài liệu dưới dạng tệp để lưu trữ hoặc dùng trong pipeline khác, dùng export.
# Xuất HTML
apidog export --project <projectId> --format html --output ./api-docs.html
# Xuất Markdown
apidog export --project <projectId> --format markdown --output ./api-docs.md
# Xuất OpenAPI 3.1
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Nếu dự án chứa nhiều dịch vụ, xem các tùy chọn lọc phạm vi:
apidog export --help
Các cờ như --scope, --api-ids và --folder-ids giúp chỉ xuất phần tài liệu cần thiết.
Ví dụ đầy đủ: từ yêu cầu đến xuất bản
Giả sử bạn gửi cho tác nhân yêu cầu sau:
Bạn: “Chúng tôi vừa thêm dịch vụ thanh toán với
POST /refundsvàGET /refunds/{id}. Hãy tài liệu hóa cả hai, viết một hướng dẫn ngắn giải thích các khóa idempotency, và xuất bản nó lên trang tài liệu của chúng tôi.”
Tác nhân có thể chạy workflow sau:
# Tạo mô hình dữ liệu dùng chung
apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json
# Tạo endpoint POST /refunds
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./post-refunds.json
apidog endpoint create --project $PID --file ./post-refunds.json
# Tạo endpoint GET /refunds/{id}
apidog cli-schema validate endpoint-create --file ./get-refund.json
apidog endpoint create --project $PID --file ./get-refund.json
# Tạo hướng dẫn idempotency
apidog cli-schema get doc-create
apidog cli-schema validate doc-create --file ./idempotency-guide.json
apidog doc create --project $PID --file ./idempotency-guide.json
# Xuất bản trang tài liệu
apidog cli-schema get docs-site-create
apidog cli-schema validate docs-site-create --file ./docs-site.json
apidog docs-site create --project $PID --file ./docs-site.json
Sau đó, bạn chỉ cần xem xét các thay đổi. Công việc trước đây yêu cầu nhiều lần chuyển đổi ngữ cảnh giữa code, tài liệu và trình duyệt trở thành một yêu cầu cùng một lần review.
Tích hợp vào workflow tác nhân hoặc CI
Vì mỗi bước là lệnh CLI, bạn có thể chạy workflow này trong CI/CD.
Ví dụ GitHub Actions tối thiểu để tái tạo tài liệu Markdown sau mỗi lần push:
- name: Tái tạo tài liệu API
run: |
npm install -g apidog-cli
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Đặt token trong secret CI, không hard-code token trong repository.
Để xem workflow tác nhân đầy đủ hơn, tham khảo:
Mẫu chung là:
- Mô tả ý định.
- Để tác nhân chuyển ý định thành lệnh CLI có schema hợp lệ.
- Xem xét kết quả.
Lưu ý về quyền
Tác nhân có thể bị chặn khi ghi vào dự án. Nếu lệnh create không chạy do quyền, dự án có thể đã tắt External AI Edit Permissions cho nhánh đó.
Bạn có hai lựa chọn:
- Bật quyền chỉnh sửa trong Project Settings → Feature Settings → AI Feature Settings trên Apidog client 2.8.32+.
- Để tác nhân làm việc trên một nhánh AI riêng và mở merge request.
Hướng dẫn cập nhật đặc tả API bằng tác nhân mô tả luồng nhánh AI. Cách làm này cũng áp dụng khi tác nhân tạo tài liệu trên nhánh được bảo vệ.
Các lỗi thường gặp
Tác nhân tự viết JSON
Đây là lỗi phổ biến nhất. Luôn áp dụng thứ tự:
cli-schema get → cli-schema validate → create
Tác nhân phải làm việc với schema thực tế từ CLI, không phải schema do mô hình tự đoán.
Thiếu ID dự án
Các lệnh doc, docs-site và export cần:
--project <projectId>
Sử dụng ID dự án từ phần cài đặt, không dùng tên dự án dễ đọc.
Nhầm lẫn giữa doc, docs-site và shared-doc
Ba loại tài nguyên này khác nhau:
-
doc: trang Markdown trong cây tài liệu. -
docs-site: website tài liệu được lưu trữ. -
shared-doc: liên kết chia sẻ.
Yêu cầu tác nhân xác định rõ loại đầu ra cần tạo trước khi chạy lệnh ghi.
Token chưa được đặt trong CI
apidog login lưu token trên máy chạy lệnh. Mỗi CI runner mới sẽ không có token đó.
Vì vậy, luôn đăng nhập trong cùng job trước khi chạy các lệnh khác:
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
$ref không trỏ đến schema tồn tại
Khi endpoint tham chiếu schema qua:
{
"$ref": "#/definitions/<schemaId>"
}
Schema phải được tạo trước endpoint. Luôn tạo schema trước, lấy schemaId, sau đó mới tạo endpoint sử dụng nó.
Câu hỏi thường gặp
Những tác nhân AI nào có thể điều khiển Apidog CLI?
Bất kỳ tác nhân nào có thể chạy lệnh shell, bao gồm Claude Code, Cursor, Codex và các coding agent tương tự. CLI không phụ thuộc vào loại tác nhân; nó cần lệnh đúng và payload hợp lệ.
Tôi có cần gói trả phí không?
Không. Apidog không phải mã nguồn mở, nhưng gói miễn phí cùng apidog-cli hỗ trợ luồng tạo và xuất bản được mô tả trong bài này.
Tác nhân có thể vô tình ghi đè tài liệu hiện có không?
Lệnh create thêm tài nguyên mới. Việc sửa tài nguyên hiện có dùng update và cần biện pháp bảo vệ riêng. Xem thêm hướng dẫn cập nhật đặc tả API.
Cách này khác gì với công cụ tạo tài liệu AI thông thường?
Công cụ tài liệu AI chung thường tạo văn bản từ code. Workflow này tạo tài liệu có cấu trúc trực tiếp trong nền tảng API: endpoint, schema, hướng dẫn Markdown và trang tài liệu đã xuất bản.
Tất cả cùng dựa trên một nguồn dữ liệu đang được nhóm chỉnh sửa, giúp giảm nguy cơ tài liệu lệch khỏi API.
Tổng kết
Một tác nhân chạy được Apidog CLI có thể tự động hóa phần tài liệu API thường bị trì hoãn:
- Tạo schema và endpoint
- Viết hướng dẫn Markdown
- Xuất bản trang tài liệu
- Xuất HTML, Markdown hoặc OpenAPI
- Tích hợp vào CI/CD
Quy tắc cốt lõi là:
Lấy schema → xác thực payload → thực hiện thao tác ghi
Cung cấp cho tác nhân quy trình này, ID dự án và quyền phù hợp. Khi đó, công việc của bạn chuyển từ viết tài liệu thủ công sang review các thay đổi mà tác nhân đã tạo.
Tải xuống Apidog để dùng CLI, hoặc xem hướng dẫn đầy đủ về Apidog CLI để tra cứu các lệnh.
Top comments (0)