DEV Community

Cover image for Cách tài liệu hóa API từ CLI
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách tài liệu hóa API từ CLI

Tài liệu API sẽ lỗi thời ngay khi ai đó chỉnh sửa đặc tả (spec) nhưng quên tạo lại tài liệu tham chiếu. Cách xử lý là loại bỏ bước tạo tài liệu thủ công: nếu có thể tạo tài liệu bằng một lệnh, bạn có thể chạy lệnh đó trong CI sau mỗi lần hợp nhất (merge).

Dùng thử Apidog ngay hôm nay

Chạy từ terminal còn giúp quy trình dễ tự động hóa hơn: bạn có thể viết script, kiểm tra diff của tệp đầu ra, hoặc để CI/AI agent kích hoạt mà không cần mở trình duyệt. Không cần thao tác qua giao diện đồ họa hoặc nhớ phải nhấn nút xuất.

Bài viết này hướng dẫn ba cách thực tế:

  1. Tạo tài liệu HTML độc lập từ tệp OpenAPI bằng Redocly CLI.
  2. Xuất Markdown bằng Widdershins.
  3. Xuất tài liệu từ dự án đang hoạt động bằng Apidog CLI, sau đó đưa vào CI.

Nếu cần so sánh công cụ, xem thêm các công cụ tài liệu REST API hàng đầu và các công cụ tài liệu API miễn phí.

Bạn cần một tệp OpenAPI 3.x để thực hiện theo. Các công cụ bên dưới thường nhận cả openapi.yaml lẫn openapi.json.

Xây dựng tài liệu tham chiếu HTML với Redocly CLI

Redocly CLI biến mô tả OpenAPI thành một trang HTML tự chứa bằng Redoc. Tệp đầu ra bao gồm nội dung, script và kiểu dáng, nên bạn có thể lưu trữ hoặc chia sẻ trực tiếp.

Cài đặt toàn cục:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

Hoặc chạy qua npx nếu không muốn cài đặt toàn cục.

Tạo tài liệu từ đặc tả:

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Theo mặc định, Redocly tạo tệp redoc-static.html trong thư mục hiện tại. Để chỉ định vị trí đầu ra:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Quy trình chỉ gồm một tệp đầu vào và một lệnh tạo HTML. Redocly hỗ trợ Swagger 2.0 cùng OpenAPI 3.0/3.1.

Dùng cách này khi bạn cần tài liệu tham chiếu HTML độc lập. Lưu ý rằng build-docs tập trung vào API reference; các nội dung dài như hướng dẫn bắt đầu, hướng dẫn xác thực hoặc migration guide cần được quản lý riêng.

Tạo Markdown với Widdershins

Nếu tài liệu của bạn nằm trong thư mục docs/, static site generator hoặc nền tảng hỗ trợ Markdown, hãy dùng Widdershins. Công cụ này chuyển đổi OpenAPI, Swagger hoặc AsyncAPI thành Markdown tương thích với Slate.

Cài đặt:

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

Xuất đặc tả sang Markdown:

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

Nếu bỏ -o, Widdershins sẽ in nội dung ra stdout. Điều này hữu ích khi bạn muốn pipe kết quả sang một lệnh khác:

widdershins openapi.yaml | tee docs/api.md
Enter fullscreen mode Exit fullscreen mode

Bạn cũng có thể cấu hình các tab ngôn ngữ cho code sample:

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

Widdershins phù hợp khi Markdown là định dạng trung tâm của quy trình tài liệu. Nếu bạn đang xây dựng luồng xuất Markdown rộng hơn, xem hướng dẫn về trình tạo tài liệu API với xuất Markdown.

Điểm cần lưu ý: cả Redocly và Widdershins đều đọc tệp tĩnh. Nếu openapi.yaml trên đĩa không đồng bộ với API mà nhóm đang chỉnh sửa, tài liệu xuất ra cũng sẽ lỗi thời.

Tạo tài liệu từ một dự án đang hoạt động với Apidog CLI

Apidog không phải mã nguồn mở, nhưng gói miễn phí kết hợp với apidog-cli cung cấp một quy trình tập trung: endpoint, schema và tài liệu viết tay nằm trong cùng một dự án; CLI xuất trực tiếp từ dự án đó.

Cách này giúp tránh sai lệch giữa tệp OpenAPI cục bộ và trạng thái API hiện tại trong công cụ thiết kế.

Cài đặt CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Nếu đây là lần đầu thiết lập, xem hướng dẫn cài đặt Apidog CLI để kiểm tra phiên bản Node và cấu hình PATH.

Xác thực bằng mã thông báo truy cập cá nhân:

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Mã thông báo được lưu lại trên máy hiện tại. Sau đó, các thao tác sẽ sử dụng ID dự án. Trước khi chạy một lệnh mới, hãy kiểm tra các cờ mà phiên bản CLI của bạn hỗ trợ:

apidog --help
Enter fullscreen mode Exit fullscreen mode

Nhập đặc tả vào dự án

Nếu bạn đã có tệp OpenAPI, hãy nhập nó vào dự án Apidog:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import hỗ trợ OpenAPI 3.x, Swagger 2.0, Postman và định dạng Apidog. Ví dụ, bạn có thể nhập Postman collection bằng cùng quy trình.

Sau khi nhập, dự án trở thành nguồn dữ liệu để CLI xuất tài liệu.

Xuất tài liệu dễ đọc

Lệnh chính là apidog export. CLI có thể xuất OpenAPI, HTML, Markdown hoặc Postman. Trước tiên, kiểm tra định dạng và cờ của phiên bản đang dùng:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Xuất tài liệu tham chiếu sang Markdown:

apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

Mở api-docs.md để kiểm tra tài liệu được tạo từ trạng thái hiện tại của dự án.

Xuất HTML:

apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

Xuất lại OpenAPI khi cần bàn giao một đặc tả di động:

apidog export \
  --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Nếu dự án chứa nhiều dịch vụ, hãy kiểm tra apidog export --help để tìm các cờ giới hạn phạm vi và ID phù hợp với phiên bản CLI của bạn.

Quản lý hướng dẫn viết tay, không chỉ API reference

Tài liệu tạo từ schema chỉ là một phần. Bạn vẫn cần các nội dung như:

  • Hướng dẫn bắt đầu
  • Hướng dẫn xác thực
  • Migration guide
  • Ghi chú tích hợp

Trong Apidog, các nội dung 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ý qua nhóm lệnh doc.

Bắt đầu bằng cách xem trợ giúp và liệt kê tài liệu hiện có:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Kết quả lệnh có thể chứa JSON và agentHints.nextSteps. Hãy dùng dữ liệu này để xác định bước tiếp theo thay vì đoán cờ hoặc payload.

Khi một thao tác cần payload JSON, kiểm tra schema trước khi gửi:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

Việc xác thực payload cục bộ giúp phát hiện trường thiếu hoặc sai cấu trúc trước khi thực hiện lệnh.

Xuất bản trang tài liệu

Sau khi hoàn thiện API reference và hướng dẫn, bạn có thể quản lý tài liệu đã xuất bản từ terminal.

Kiểm tra hai nhóm lệnh:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

Phân biệt các khái niệm:

  • 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 tài liệu có thể chia sẻ.

Dùng docs-site khi muốn quản lý trang tài liệu công khai bằng CLI. Dùng shared-doc khi chỉ cần tạo liên kết gửi cho đối tác hoặc người dùng.

Quy trình có thể được script hóa:

  1. Nhập lại đặc tả hoặc cập nhật dự án.
  2. Xuất lại tài liệu.
  3. Chạy lệnh xuất bản.
  4. Để trang tài liệu phản ánh nội dung mới.

Tích hợp vào CI

Lợi ích chính của CLI là khả năng lặp lại. Khi lệnh chạy được trên máy cục bộ, bạn có thể đưa nó vào pipeline.

Ví dụ GitHub Actions tối thiểu để tạo lại tài liệu Markdown:

- name: Regenerate API docs
  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
Enter fullscreen mode Exit fullscreen mode

Lưu ý:

  • Lưu token trong secrets, không ghi trực tiếp vào workflow.
  • Mỗi runner CI mới cần chạy apidog login --with-token trong chính job đó.
  • Nếu dùng Redocly hoặc Widdershins, cấu trúc CI tương tự; chỉ thay lệnh xuất.

Ví dụ với Redocly:

- name: Build API reference
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Ví dụ với Widdershins:

- name: Generate Markdown API docs
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api.md
Enter fullscreen mode Exit fullscreen mode

Những vướng mắc thường gặp

ID dự án sai hoặc thiếu.

Các lệnh Apidog như export, doc và docs-site cần --project <projectId>. Đây là ID trong cài đặt dự án, không phải tên dự án hiển thị.

Token chưa được đặt trong CI.

apidog login lưu token trên máy chạy lệnh. Runner CI mới không có token đã lưu, nên cần đăng nhập lại trong cùng job trước khi xuất tài liệu.

Xuất từ tệp OpenAPI lỗi thời.

Redocly và Widdershins luôn đọc tệp được truyền vào. Nếu openapi.yaml không được cập nhật, tài liệu tạo ra cũng không cập nhật. Xuất trực tiếp từ dự án giúp giảm vấn đề này.

Đoán cờ thay vì đọc --help.

Cờ của export, doc, docs-site và shared-doc có thể thay đổi theo phiên bản CLI. Luôn kiểm tra trước:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

Tóm lại

Chọn công cụ theo định dạng đầu ra và nguồn dữ liệu của bạn:

  • Dùng Redocly CLI khi cần một trang HTML API reference độc lập.
  • Dùng Widdershins khi cần Markdown cho static site hoặc repository.
  • Dùng Apidog CLI khi cần xuất API reference, quản lý hướng dẫn Markdown và xuất bản tài liệu từ cùng một dự án.

Mọi lệnh trong bài đều có thể chạy trong script và CI. Thiết lập một lần, sau đó tài liệu có thể được tạo lại sau mỗi thay đổi API.

Tải xuống Apidog để dùng CLI và thử quy trình xuất trên dự án của bạn, hoặc tìm hiểu thêm cách Apidog hỗ trợ quy trình API-first.

Top comments (0)