DEV Community

Cover image for Công cụ CLI Gọn nhẹ Tốt nhất để Tạo Tài liệu API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Công cụ CLI Gọn nhẹ Tốt nhất để Tạo Tài liệu API

Bạn có một tệp OpenAPI và cần tạo tài liệu nhanh chóng. Bạn không muốn dựng một dịch vụ, đăng nhập vào cổng thông tin hay thêm một pipeline build nặng với hàng loạt dependency npm. Mục tiêu là chạy một lệnh đọc đặc tả và tạo ra Markdown hoặc một tệp HTML độc lập để có thể commit, gửi đi hoặc host ở bất kỳ đâu.

Dùng thử Apidog ngay hôm nay

Danh sách này tập trung vào các công cụ gọn nhẹ: binary, lệnh npx một dòng hoặc gói cài một lần. Chúng chạy tốt trong terminal và CI, yêu cầu ít cấu hình, và chỉ làm một việc: biến đặc tả API thành tài liệu. Nếu bạn cần nền tảng có GUI đầy đủ hơn, hãy xem bài tổng hợp các công cụ tài liệu API REST hàng đầu. Về định dạng đầu vào, Đặc tả OpenAPI là nguồn tham chiếu chính thức mà các công cụ dưới đây đều phân tích.

Điều gì làm cho một công cụ CLI trở nên “nhẹ” đối với tài liệu API?

“Nhẹ” không đồng nghĩa với ít tính năng. Trong bối cảnh tài liệu API, nó thường được xác định bởi bốn tiêu chí:

  1. Ít dependency

    Một binary hoặc một gói npm thường nhẹ hơn một framework yêu cầu runtime, bundler và plugin.

  2. Chạy ngay với cấu hình tối thiểu

    Lý tưởng nhất là trỏ lệnh vào openapi.yaml và nhận đầu ra ngay:

   tool openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

  1. Đầu ra rõ ràng, một mục đích

    Đặc tả vào, Markdown hoặc HTML ra. Không cần vận hành server hay nền tảng tài liệu phức tạp.

  2. Dùng được ở local lẫn CI

    Không cần GUI, không cần duy trì máy chủ. Cùng một lệnh phải chạy được trên laptop và trong pipeline CI.

Để xem thêm các lựa chọn miễn phí có cả nền tảng GUI, hãy tham khảo các công cụ tài liệu API miễn phí. Phần dưới đây chỉ tập trung vào workflow CLI.

Widdershins

Widdershins là lựa chọn tối giản để chuyển OpenAPI thành Markdown. Công cụ hỗ trợ OpenAPI 3, Swagger 2 và AsyncAPI, không render website và không chạy server.

Cài đặt và tạo tài liệu:

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Bạn nhận được một tệp api-docs.md có thể:

  • Commit cùng repository.
  • Review bằng Git diff.
  • Đưa vào một static site generator.
  • Render tiếp bằng Slate hoặc hệ thống tài liệu khác.

Một số cờ hữu ích:

# Bỏ phần YAML header trong Markdown
widdershins openapi.yaml -o api-docs.md --omitHeader

# Kiểm soát các tab ngôn ngữ cho code sample
widdershins openapi.yaml -o api-docs.md --language_tabs 'javascript:JavaScript' 'python:Python'
Enter fullscreen mode Exit fullscreen mode

Phù hợp khi: bạn cần chuyển đặc tả thành Markdown nhanh để commit hoặc tích hợp vào hệ thống tài liệu hiện có.

Lưu ý: Widdershins chỉ tạo Markdown. Nó không cung cấp giao diện, style, trang “try it” hay hosting. Bạn sẽ cần một công cụ khác để render Markdown thành website.

OpenAPI Generator

OpenAPI Generator thường được dùng để sinh SDK client, nhưng cũng có các generator dành cho tài liệu. Hai generator đáng dùng trong trường hợp này là:

  • markdown: tạo một thư mục chứa tài liệu Markdown.
  • html2: tạo tài liệu HTML.

Cài CLI wrapper và chạy generator:

npm install -g @openapitools/openapi-generator-cli

# Tạo tài liệu Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# Tạo tài liệu HTML
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

Ví dụ dùng trong CI:

openapi-generator-cli generate \
  -g html2 \
  -i ./openapi.yaml \
  -o ./dist/api-docs
Enter fullscreen mode Exit fullscreen mode

CLI wrapper npm vẫn tải một tệp JAR được chạy qua JDK ở phía dưới, nên lần chạy đầu nặng hơn Widdershins. Tuy nhiên, sau khi tải xong, workflow tạo tài liệu vẫn chỉ là một lệnh.

Phù hợp khi: bạn đã dùng OpenAPI Generator để tạo SDK và muốn tái sử dụng cùng một công cụ cho tài liệu.

Lưu ý: đầu ra chủ yếu dựa trên template và tương đối đơn giản. Nếu chỉ cần tạo tài liệu từ đặc tả, Widdershins hoặc Redocly CLI có thể gọn hơn.

Redocly CLI (build-docs)

Nếu mục tiêu là một tệp HTML độc lập, dễ chia sẻ và có giao diện hoàn chỉnh, Redocly CLI là lựa chọn trực tiếp.

Chạy bằng npx, không cần cài global:

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Theo mặc định, lệnh tạo tệp:

redoc-static.html
Enter fullscreen mode Exit fullscreen mode

Đặt tên tệp đầu ra bằng --output:

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

Ví dụ pipeline CI đơn giản:

npx @redocly/cli build-docs ./openapi.yaml --output ./dist/api.html
Enter fullscreen mode Exit fullscreen mode

Sau đó, publish thư mục dist/ lên GitHub Pages, Netlify, Vercel hoặc bất kỳ static host nào.

Phù hợp khi: bạn cần một trang API reference HTML hoàn chỉnh chỉ từ một lệnh.

Lưu ý: đây là một trang HTML độc lập, không phải cổng tài liệu nhiều trang. Các tính năng theme và preview nâng cao hơn thuộc các gói trả phí của Redocly. Nếu đang so sánh các renderer tương tự, xem thêm các lựa chọn thay thế Redocly và các lựa chọn thay thế Scalar.

Slate

Slate khác với các công cụ trên: nó không đọc OpenAPI trực tiếp. Đây là static site generator dành cho tài liệu API viết bằng tay với Markdown, nổi bật với bố cục ba cột gồm điều hướng, nội dung và code sample.

Slate chạy trên Middleman nên yêu cầu Ruby và Bundler. Sau khi clone repository Slate và cài dependency, hãy build:

bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Lệnh này tạo static site trong thư mục build/.

Một workflow phổ biến là kết hợp Widdershins và Slate:

# 1. Chuyển OpenAPI sang Markdown
widdershins openapi.yaml -o source/index.html.md

# 2. Build website bằng Slate
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Phù hợp khi: bạn cần tài liệu có tính biên tập, hướng dẫn theo luồng sử dụng và kiểm soát hoàn toàn cấu trúc nội dung.

Lưu ý: Slate là lựa chọn nặng nhất trong danh sách vì cần Ruby toolchain. Nó cũng không tự đọc OpenAPI; bạn phải cung cấp Markdown hoặc nội dung viết tay.

Apidog CLI (export và doc)

Các công cụ mã nguồn mở ở trên thường giải quyết một phần của workflow: chuyển đổi đặc tả, render HTML hoặc host tài liệu. Nếu API của bạn đã được quản lý trong một dự án, việc ghép nhiều công cụ có thể làm pipeline phức tạp hơn.

apidog-cli là CLI đồng hành với Apidog, cho phép export một dự án API sang Markdown hoặc HTML.

Cài CLI và xác thực bằng token:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Export tài liệu dự án sang Markdown:

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

Hoặc export sang HTML:

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

CLI cũng hỗ trợ quản lý tài nguyên tài liệu trong dự án:

# Liệt kê tài liệu Markdown của dự án
apidog doc list --project <projectId>

# Liệt kê các docs site đã xuất bản
apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Đầu ra có cấu trúc JSON, phù hợp để dùng trong script, CI hoặc chuyển sang bước tự động hóa khác. Xem hướng dẫn đầy đủ về Apidog CLI để biết chi tiết về xác thực, project và các nhóm lệnh.

Apidog không phải công cụ mã nguồn mở hay binary đơn mục đích. Đây là nền tảng freemium, và CLI giao tiếp với dự án được lưu trữ. CLI cũng không thay thế việc kiểm tra OpenAPI hoặc lint style guide như Redocly và Spectral.

Điểm mạnh của workflow này là đường dẫn trực tiếp từ một dự án API đang được duy trì sang Markdown hoặc HTML có thể chia sẻ, thay vì phải tự nối converter, renderer và static host. Nếu cần export Markdown cụ thể, hãy xem Trình tạo tài liệu API với xuất Markdown.

Cách chọn

Chọn công cụ dựa trên định dạng đầu vào và đầu ra bạn cần.

Công cụ Tốt nhất cho Cài đặt Mã nguồn mở? Đầu ra
Widdershins Chuyển đặc tả sang Markdown nhanh npm i -g widdershins Có (MIT) Markdown
OpenAPI Generator Tạo tài liệu cùng với SDK npm i -g @openapitools/openapi-generator-cli Có (Apache 2.0) Markdown hoặc HTML
Redocly CLI Một trang HTML được trau chuốt npx @redocly/cli Có (MIT, open core) HTML độc lập
Slate Trang tài liệu viết và biên tập thủ công Ruby + Bundler Có (Apache 2.0) Static site
Apidog CLI Export từ một dự án API đang hoạt động npm i -g apidog-cli Không (phiên bản miễn phí) Markdown hoặc HTML

Tóm tắt nhanh:

  • Có tệp OpenAPI và cần Markdown để commit: dùng Widdershins.
  • Cần một trang HTML có thể chia sẻ ngay: dùng Redocly CLI với build-docs.
  • Đã dùng OpenAPI Generator để tạo SDK: dùng luôn generator markdown hoặc html2.
  • Muốn viết tài liệu thủ công với layout API cổ điển: dùng Slate.
  • API đã nằm trong một dự án và cần export kèm quản lý tài liệu: dùng Apidog CLI.

Để xem thêm các lựa chọn miễn phí, hãy tham khảo các công cụ tài liệu API miễn phí.

Tổng kết

Nguyên tắc thực tế là chọn công cụ nhỏ nhất tạo được đầu ra bạn cần:

  • Widdershins phù hợp cho workflow OpenAPI → Markdown.
  • Redocly CLI phù hợp cho OpenAPI → HTML độc lập.
  • OpenAPI Generator phù hợp khi tài liệu là một phần trong pipeline sinh SDK.
  • Slate phù hợp khi tài liệu cần được viết và biên tập thủ công.
  • Apidog CLI phù hợp khi nguồn API là một dự án đang được quản lý thay vì một tệp đặc tả rời rạc.

Nếu API của bạn đã nằm trong một dự án, hãy Tải Apidog và thử apidog export. Lệnh này có thể được đưa trực tiếp vào CI để tài liệu được xây dựng lại mỗi khi API thay đổi.

Top comments (0)