Cách AI tạo tài liệu API bằng Apidog CLI

Tài liệu API là công việc mà mọi người đều đồng ý là quan trọng nhưng không ai muốn chịu trách nhiệm. Một endpoint mới được triển khai, tài liệu tham khảo chậm hơn một tuần, và hướng dẫn bắt đầu lại mô tả một luồng xác thực mà bạn đã thay thế từ hai sprint trước. Công việc thì thật đấy, nhưng nó lặp đi lặp lại và dễ bị trì hoãn.

Sự kết hợp đó (quan trọng, lặp đi lặp lại, có thể trì hoãn) chính xác là những gì một tác nhân AI giỏi. Nếu tác nhân của bạn có thể chạy một lệnh terminal, nó có thể tạo các endpoint, viết các hướng dẫn bằng văn bản xung quanh chúng và xuất bản một trang tài liệu, tất cả chỉ từ một yêu cầu bằng ngôn ngữ tự nhiên. CLI của Apidog là thứ giúp điều đó trở thành hiện thực: mọi hành động tài liệu đều là một lệnh có thể script được với đầu ra JSON có cấu trúc mà tác nhân có thể đọc và thực hiện.

nút

Tại sao là CLI, không phải GUI hay máy chủ MCP

Có ba cách mà một tác nhân có thể tương tác với tài liệu API của bạn, và chúng giải quyết các vấn đề khác nhau. Nắm rõ sự khác biệt này là yếu tố quyết định giữa việc bạn phải vật lộn với các công cụ của mình và việc sử dụng công cụ phù hợp với công việc.

Phương pháp	Hướng	Ai điều khiển	Có thể xem sự khác biệt?
GUI	Người chỉnh sửa trong trình duyệt	Một người, nhấp chuột	Không
Máy chủ MCP	Đọc đặc tả của bạn → viết mã	Một tác nhân, trong trình soạn thảo của bạn	Trong kho mã của bạn, không phải tài liệu
CLI	Tự viết tài liệu	Một tác nhân, trong terminal	Có, mọi lệnh đều được ghi lại

Một máy chủ MCP rất xuất sắc khi bạn muốn một tác nhân đọc định nghĩa API của bạn và tạo mã client dựa trên nó. Luồng tài liệu qua MCP của Cursor là một ví dụ điển hình. Nhưng đó lại là điều ngược lại với những gì chúng ta muốn ở đây. Chúng ta muốn tác nhân tạo ra tài liệu: tạo các endpoint, viết hướng dẫn Markdown và xuất bản một trang web.

Đối với điều đó, CLI thắng thế ở ba điểm. Nó mang tính xác định: cùng một lệnh tạo ra cùng một kết quả. Nó có thể script được: toàn bộ luồng có thể tích hợp vào CI. Và nó trả về JSON trong mỗi cuộc gọi, bao gồm một trường agentHints.nextSteps cho tác nhân biết nó có thể làm gì tiếp theo. Điểm cuối cùng đó quan trọng hơn những gì nghe thấy: nó có nghĩa là tác nhân không tự đoán đường đi mà đang tuân theo các gợi ý của chính CLI.

Thiết lập môi trường cho tác nhân

Cài đặt CLI và xác thực một lần. Hướng dẫn cài đặt của chúng tôi bao gồm các phiên bản Node và PATH; hướng dẫn xác thực bao gồm các token và bí mật CI.

npm install -g apidog-cli
apidog login --with-token <TOKEN>

Lấy token từ ứng dụng Apidog trong phần avatar người dùng → Cài đặt tài khoản (Account Settings) → Token truy cập API (API Access Token). Nó được lưu trữ cục bộ sau khi đăng nhập, vì vậy tác nhân không cần truyền nó trong mỗi cuộc gọi.

Mọi thao tác ghi đều được thực hiện dựa trên một ID dự án, bạn sẽ tìm thấy nó trong Cài đặt dự án (Project Settings) → Cài đặt cơ bản (Basic Settings), hoặc bằng cách chạy:

apidog project list

Bất kỳ tác nhân mã hóa nào có thể chạy lệnh shell đều hoạt động ở đây: Claude Code, Cursor, Codex và các tác nhân khác. CLI không quan tâm tác nhân nào gọi nó; nó chỉ quan tâm các lệnh và tải trọng là chính xác. Điều này đưa chúng ta đến một quy tắc duy nhất giúp toàn bộ quá trình trở nên đáng tin cậy.

Nghi thức ghi mà tác nhân phải tuân theo

Các lệnh tài liệu tạo tài nguyên nhận một tệp JSON. Tác nhân của bạn không bao giờ nên tự tạo JSON đó từ bộ nhớ. Tên trường do mô hình tự nghĩ ra là nguyên nhân số một gây ra các lần chạy thất bại. CLI cung cấp schema chính xác cho mọi thao tác ghi, và trình tự đúng luôn là bốn bước sau:

# 1. Hỏi CLI payload trông như thế nào
apidog cli-schema get doc-create

# 2. Tạo tệp JSON từ schema đó

# 3. Xác thực trước khi ghi (bắt lỗi trường bị thiếu cục bộ)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Chỉ bây giờ mới chạy lệnh thực sự
apidog doc create --project <projectId> --file ./doc.json

Hãy đưa vòng lặp này vào hướng dẫn của tác nhân. Nó biến "mô hình tự tạo một trường" thành "bộ xác thực đã từ chối nó trên máy của tôi", đó là sự khác biệt giữa một lần chạy sạch và một bản dựng lỗi. Dưới đây là khối quy tắc bạn có thể dán trực tiếp vào lời nhắc hệ thống của tác nhân hoặc tệp CLAUDE.md / .cursorrules:

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ế.

Năm dòng đó là những gì phân biệt một tác nhân đáng tin cậy trong việc xuất bản tài liệu với một tác nhân chỉ đoán payload vào ngõ cụt.

Bước 1: Tạo tài liệu tham khảo từ các endpoint và schema

Trong Apidog, tài liệu tham khảo API của bạn được tạo ra từ các endpoint và schema dữ liệu trong dự án. Vì vậy, công việc đầu tiên của tác nhân là tạo ra chúng. Giả sử bạn nói với nó:

“Thêm một endpoint POST /refunds nhận một ID đơn hàng và một số tiền, và tài liệu hóa các phản hồi thành công và lỗi xác thực của nó.”

Tác nhân tạo mô hình dữ liệu có thể tái sử dụng trước, sau đó là endpoint tham chiếu đến nó. Chạy apidog cli-schema get schema-create cho thấy một schema dữ liệu nhận một name và một đối tượng jsonSchema tiêu chuẩn. Vì vậy, tác nhân viết một cái gì đó tương tự như 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:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Bây giờ là endpoint. Schema endpoint-create yêu cầu method và path, đồng thời cho phép bạn tham chiếu mô hình dữ liệu bạn vừa tạo với một $ref theo định dạng #/definitions/{schemaId}. Tác nhân viết refunds-endpoint.json:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

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 đã tồn tại, được hiển thị từ cùng một định nghĩa mà nhóm của bạn chỉnh sửa. Không có bước "xuất tài liệu" riêng biệt cho tài liệu tham khảo; nó hoạt động trực tiếp trong dự án ngay khi endpoint được triển khai. Đó là lợi ích của một nguồn ưu tiên schema: tài liệu tham khảo không thể bị lệch, bởi vì nó chính là schema.

Bước 2: Viết hướng dẫn, không chỉ tài liệu tham khảo

Một tài liệu tham khảo được tạo từ schema chỉ là một nửa của tài liệu tốt. Nửa còn lại là văn bản: một trang bắt đầu nhanh, hướng dẫn xác thực, ghi chú di chuyển. Trong Apidog, những tài liệu này nằm trong cây tài liệu của dự án dưới dạng tài liệu Markdown, được quản lý bởi nhóm lệnh doc.

Schema doc-create chỉ yêu cầu một name; content chứa Markdown, và folderId đặt nó vào cây tài liệu (0 là thư mục gốc). Vì vậy, một bản hướng dẫn nhanh mà tác nhân soạn thảo trở thành 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
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

Đây là nơi tác nhân thể hiện giá trị của nó. Yêu cầu nó “viết một hướng dẫn nhanh giúp nhà phát triển mới từ khóa API đến khoản hoàn tiền đầu tiên,” và nó sẽ soạn thảo Markdown, đóng gói nó vào payload mà schema mong đợi, xác thực và tạo tài liệu. Không cần trình duyệt, không cần sao chép-dán. Bởi vì nội dung chỉ là một trường chuỗi, tác nhân có thể viết hướng dẫn dài hoặc chi tiết tùy theo yêu cầu của nhiệm vụ.

Bước 3: Xuất bản trang tài liệu

Với tài liệu tham khảo và hướng dẫn đã có sẵn, tác nhân cũng có thể xuất bản từ terminal. Hai nhóm lệnh xử lý việc này, và một sự phân biệt tên gọi thường xuyên làm mọi người bối rối:

doc: một tài liệu Markdown bên trong cây API của dự án (những gì bạn đã tạo ở bước 2).
docs-site: trang tài liệu công khai, được lưu trữ.
shared-doc: một liên kết có thể chia sẻ để gửi cho đối tác, không phải một trang web hoàn chỉnh.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Sử dụng docs-site khi bạn muốn một trang web công khai được định nghĩa từ terminal, và shared-doc khi bạn chỉ cần một liên kết để gửi cho ai đó. Bởi vì cả hai đều là lệnh, việc xuất bản trở thành một bước có thể script được mà tác nhân chạy sau mỗi lần thay đổi tài liệu; trang web được lưu trữ sẽ phản ánh cập nhật ngay khi lệnh trả về.

Bước 4 (tùy chọn): Xuất bản sao di động

Đôi khi bạn muốn tài liệu dưới dạng tệp: một trang HTML để lưu trữ ở nơi khác, Markdown cho trình tạo trang tĩnh, hoặc OpenAPI để chuyển cho các bên liên quan. Lệnh export tạo ra cả ba:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

Nếu dự án của bạn chứa nhiều dịch vụ và bạn chỉ muốn tài liệu hóa một phần của nó, apidog export --help hiển thị các cờ --scope, --api-ids và --folder-ids để thu hẹp phạm vi đầu ra. Một dự án duy nhất có thể xuất một tệp tài liệu cho mỗi dịch vụ theo cách đó.

Một ví dụ đầy đủ, từ đầu đến cuối

Dưới đây là toàn bộ vòng lặp dưới dạng một yêu cầu bằng ngôn ngữ tự nhiên và các lệnh mà tác nhân chạy để đáp ứng nó.

Bạn: “Chúng tôi vừa thêm dịch vụ thanh toán với POST /refunds và 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, tuân theo các quy tắc của nó, sẽ chạy:

# Tạo mô hình dữ liệu dùng chung
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Tạo cả hai endpoint
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Soạn thảo hướng dẫn idempotency dưới dạng tài liệu Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# Xuất bản
apidog docs-site create --project $PID --file ./docs-site.json

Bạn xem xét sự khác biệt kết quả, và dịch vụ thanh toán đã được tài liệu hóa và hoạt động. Điều từng mất cả buổi chiều để chuyển đổi ngữ cảnh giờ chỉ là một yêu cầu và một lần xem xét.

Kết nối nó vào vòng lặp tác nhân hoặc CI

Bởi vì mỗi bước là một lệnh, toàn bộ luồng có thể tích hợp vào CI hoặc vòng lặp tác vụ của tác nhân. Một bước tối thiểu tái tạo và commit tài liệu tham khảo Markdown của bạn trong 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

Để có cái nhìn đầy đủ hơn về việc chạy một tác nhân với CLI từ đầu đến cuối, hãy xem Từ PRD đến vòng lặp thử nghiệm và Cách thiết lập 5 tác nhân AI để xây dựng một API hoàn chỉnh. Mẫu hình trong cả hai trường hợp đều giống như ở đây: mô tả ý định, để tác nhân dịch nó thành các lệnh gọi CLI đã được xác thực, xem xét kết quả.

Một lưu ý về quyền

Việc ghi vào một dự án thông qua một tác nhân có thể bị kiểm soát. Nếu một lệnh create bị chặn, dự án đã tắt Quyền chỉnh sửa AI bên ngoài (External AI Edit Permissions) cho nhánh đó. Bạn có hai lựa chọn thẳng thắn: bật quyền chỉnh sửa trực tiếp trong Cài đặt dự án (Project Settings) → Cài đặt tính năng (Feature Settings) → Cài đặt tính năng AI (AI Feature Settings) (client Apidog 2.8.32+), hoặc để tác nhân làm việc trên một nhánh AI biệt lập và mở một yêu cầu hợp nhất (merge request). Hướng dẫn đi kèm về cập nhật đặc tả API của bạn giải thích đầy đủ luồng nhánh AI, và nó cũng áp dụng tương tự khi tác nhân đang tạo tài liệu trên một nhánh được bảo vệ.

Các lỗi thường gặp

Tác nhân tự viết tay JSON. Đây là lỗi số một. Hãy thực thi cli-schema get → cli-schema validate → create trong hướng dẫn của tác nhân để nó làm việc với schema thực, không phải schema tự đoán.
Thiếu ID dự án. Mọi lệnh gọi doc, docs-site và export đều cần --project <projectId>, ID từ cài đặt, không phải tên dự án dễ đọc. Hầu hết các báo cáo "lỗi" đều do điều này.
Nhầm lẫn giữa doc, docs-site và shared-doc. Chúng là ba thứ khác nhau: một trang Markdown trong cây, một trang web được lưu trữ và một liên kết chia sẻ. Hãy yêu cầu tác nhân xác nhận nhiệm vụ muốn cái nào trước khi nó viết.
Token chưa được đặt trong CI. apidog login lưu token trên máy chạy nó. Một trình chạy CI mới không có, vì vậy hãy chạy login --with-token trong cùng một công việc trước bất kỳ lệnh nào và giữ token trong một bí mật.
Một $ref không trỏ đến đâu. Khi một endpoint tham chiếu một mô hình dữ liệu với #/definitions/{schemaId}, schema đó phải tồn tại trước. Hãy tạo schema trước các endpoint sử dụng chúng.

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: Claude Code, Cursor, Codex và các tác nhân mã hóa tương tự. CLI không phụ thuộc vào tác nhân; nó chỉ cần các lệnh chính xác và payload hợp lệ.
Tôi có cần gói trả phí không? Không. Apidog không phải là mã nguồn mở, nhưng gói miễn phí cộng với apidog-cli bao gồm luồng tạo và xuất bản được mô tả ở đâ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. Sửa đổi tài nguyên hiện có sử dụng update, hoạt động khác và cần các biện pháp bảo vệ riêng; điều đó được đề cập trong hướng dẫn đi kèm về cập nhật đặc tả API của bạn.
Điều này khác với trình tạo tài liệu AI như thế nào? Các công cụ tài liệu AI chung tạo văn bản từ mã của bạn. Cái này tạo ra tài liệu có cấu trúc bên trong nền tảng API của bạn (endpoint, schema, hướng dẫn và một trang web đã xuất bản) từ một nguồn sống duy nhất không thể lệch khỏi những gì nhóm của bạn chỉnh sửa.

Tổng kết

Một tác nhân có thể chạy Apidog CLI có thể đảm nhiệm phần tài liệu mà mọi người luôn trì hoãn: nó tạo các endpoint, viết hướng dẫn xung quanh chúng và xuất bản trang web. Tất cả từ một yêu cầu bằng ngôn ngữ tự nhiên, với việc xác thực schema bảo vệ mọi thao tác ghi. Vai trò của bạn chuyển từ viết tài liệu sang xem xét sự khác biệt.

Quy tắc duy nhất làm cho nó đáng tin cậy là nghi thức ghi: lấy schema, xác thực, sau đó tạo. Cung cấp cho tác nhân của bạn vòng lặp đó, khối quy tắc năm dòng ở trên và một ID dự án, và việc tài liệu hóa sẽ không còn là một công việc vất vả đi sau mã nguồn nữa. Tải xuống Apidog để có CLI, hoặc đọc hướng dẫn đầy đủ về Apidog CLI để có tài liệu tham khảo lệnh đầy đủ.

nút