Công cụ CLI mã nguồn mở miễn phí cho tài liệu API

Khi chọn công cụ tạo tài liệu API, giấy phép là một phần của quyết định kỹ thuật. Một trình tạo mã nguồn mở cho phép bạn đọc mã, tự lưu trữ đầu ra, phân nhánh khi dự án ngừng phát triển và tránh giới hạn chỗ ngồi hoặc tường phí cho các tính năng đã triển khai. Với một tác vụ chạy trong mọi bản dựng CI, điều này quan trọng không kém chất lượng đầu ra.

Dùng thử Apidog ngay hôm nay

Danh sách này tập trung vào các công cụ tài liệu API mã nguồn mở chạy từ dòng lệnh. Mỗi công cụ đều có mã nguồn trên GitHub, dùng giấy phép MIT hoặc Apache 2.0 và có thể chạy miễn phí mà không cần tài khoản. Bạn chỉ cần cung cấp tệp OpenAPI hoặc Swagger để nhận Markdown, HTML tĩnh hoặc một website tài liệu tự lưu trữ.

Tôi sẽ nêu rõ giấy phép và cách tự lưu trữ của từng công cụ. Nếu cần khảo sát cả các nền tảng GUI, xem bài tổng hợp các công cụ tài liệu API REST hàng đầu. Đặc tả OpenAPI là định dạng đầu vào mà tất cả công cụ bên dưới đều hỗ trợ, vì vậy hãy bắt đầu bằng một đặc tả hợp lệ.

Lưu ý: Apidog xuất hiện gần cuối bài nhưng không phải là công cụ mã nguồn mở. Đây là nền tảng freemium thương mại, được đưa vào để đối chiếu khi quy trình mã nguồn mở không đáp ứng đủ nhu cầu.

Điều gì khiến một công cụ tài liệu CLI thực sự “mã nguồn mở”?

“Mã nguồn mở” không chỉ có nghĩa là miễn phí để tải xuống. Với một công cụ được tích hợp vào pipeline build, hãy kiểm tra ba yếu tố sau.

1. Giấy phép rõ ràng

MIT hoặc Apache 2.0 cho phép dùng, sửa đổi và phân phối lại công cụ cho mục đích thương mại mà không cần xin phép riêng.

• MIT: ngắn gọn, dễ dùng.
• Apache 2.0: bổ sung điều khoản cấp bằng sáng chế rõ ràng; thường phù hợp với các yêu cầu pháp lý thận trọng hơn.

Mọi công cụ mã nguồn mở trong bài đều dùng một trong hai giấy phép này.

2. Đầu ra có thể tự lưu trữ

Mục tiêu của tài liệu mở là không phụ thuộc vào máy chủ của nhà cung cấp. Các công cụ này tạo ra:

• Markdown để commit vào repository;
• một tệp HTML độc lập;
• hoặc thư mục HTML/CSS/JS tĩnh.

Bạn có thể triển khai đầu ra lên GitHub Pages, S3 hoặc Nginx. Website tài liệu vẫn hoạt động ngay cả khi dự án phía sau công cụ không còn được duy trì.

3. Tình trạng bảo trì và cộng đồng

Mã nguồn chỉ có giá trị khi vẫn có thể vận hành. Hãy kiểm tra commit gần đây, issue đang mở và hoạt động của fork trước khi đưa công cụ vào CI lâu dài.

Để xem thêm lựa chọn miễn phí gồm cả mã nguồn mở và freemium, xem các công cụ tài liệu API miễn phí.

Redocly CLI

Redocly CLI là cách nhanh để tạo tài liệu tham khảo HTML hoàn chỉnh từ một đặc tả OpenAPI. CLI và bộ kết xuất Redoc được cấp phép MIT và có mã nguồn trên GitHub. Một số tính năng cổng thông tin được lưu trữ thuộc sản phẩm trả phí, nhưng lệnh build-docs nằm trong phần mã nguồn mở.

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

Lệnh này tạo một tệp HTML duy nhất dựa trên Redoc. Bạn có thể:

1. Mở trực tiếp bằng trình duyệt để kiểm tra.
2. Đưa lên máy chủ tĩnh.
3. Đính kèm vào artifact hoặc release của CI.

Sau khi package đã được cache, công cụ có thể chạy ngoại tuyến và đầu ra không phụ thuộc vào máy chủ của Redocly.

Phù hợp nhất cho: tài liệu tham khảo API một trang, tự lưu trữ, được tạo từ một lệnh.

Giới hạn: đầu ra là một trang thay vì cổng thông tin nhiều trang. Các tùy chọn giao diện phong phú hơn thuộc cấp độ trả phí. Nếu đang đánh giá các trình kết xuất, xem các lựa chọn thay thế Redocly.

Widdershins

Widdershins là công cụ chuyển đổi thuần túy, dùng giấy phép MIT. Nó đọc OpenAPI 3, Swagger 2 hoặc AsyncAPI và xuất Markdown.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Vì đầu ra là Markdown thuần túy, bạn có thể:

• commit tài liệu vào Git;
• review thay đổi tài liệu trong pull request;
• dùng với bất kỳ static site generator nào.

Markdown do Widdershins tạo tương thích với Slate. Một số cờ hữu ích:

# Bỏ front-matter/header mặc định
widdershins openapi.yaml -o api-docs.md --omitHeader

# Chọn ngôn ngữ cho code sample
widdershins openapi.yaml -o api-docs.md --language_tabs javascript:JavaScript python:Python

Phù hợp nhất cho: chuyển đặc tả thành Markdown có thể kiểm soát phiên bản.

Giới hạn: Widdershins không tạo website hoặc style. Bạn cần thêm Slate, Docusaurus hoặc một trình tạo trang tĩnh khác để hiển thị Markdown.

OpenAPI Generator

OpenAPI Generator dùng giấy phép Apache 2.0 và được cộng đồng duy trì. Dự án được phân nhánh từ Swagger Codegen năm 2018. Ngoài SDK client, nó có các generator cho tài liệu:

• markdown: tạo thư mục Markdown;
• html2: tạo tài liệu HTML độc lập.

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

# Tạo Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# Tạo HTML
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

Dùng công cụ này khi bạn muốn tạo SDK và tài liệu từ cùng một OpenAPI spec trong một pipeline.

Phù hợp nhất cho: dùng chung một công cụ cho SDK và tài liệu, với giấy phép Apache 2.0.

Giới hạn: npm wrapper tải tệp Java JAR ở lần chạy đầu tiên. Đầu ra theo template khá cơ bản; nếu chỉ cần tài liệu, Redocly CLI hoặc Widdershins có thể nhẹ hơn.

Swagger Codegen

Swagger Codegen là trình tạo dựa trên template gốc của hệ sinh thái Swagger, dùng giấy phép Apache 2.0 và vẫn được SmartBear duy trì.

Với tài liệu, bạn có thể dùng:

• html: tạo tài liệu tham khảo tĩnh một trang;
• dynamic-html: tạo website tương tác nhỏ.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

Nếu nhóm đã tiêu chuẩn hóa trên toolchain Swagger, Swagger Codegen giúp duy trì tính nhất quán với các công cụ tạo stub hiện có.

Phù hợp nhất cho: đội ngũ đã đầu tư vào hệ sinh thái Swagger.

Giới hạn: giống OpenAPI Generator, công cụ phụ thuộc Java. Tốc độ phát triển chậm hơn nhánh cộng đồng OpenAPI Generator. Với dự án mới, OpenAPI Generator thường là lựa chọn tích cực hơn; Swagger Codegen phù hợp khi cần tính liên tục.

Docusaurus với plugin OpenAPI

Nếu một tệp HTML duy nhất là chưa đủ và bạn cần một website tài liệu hoàn chỉnh, có versioning, Docusaurus là lựa chọn mã nguồn mở phổ biến. Docusaurus dùng giấy phép MIT, do Meta xây dựng, và hỗ trợ Markdown/MDX.

Để sinh tài liệu từ OpenAPI, dùng plugin docusaurus-openapi-docs, cũng được cấp phép MIT và do Palo Alto Networks duy trì.

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

Sau khi cấu hình plugin với đường dẫn đến file OpenAPI, lệnh gen-api-docs sẽ chuyển đổi đặc tả thành các trang MDX trong site Docusaurus. Bạn có thể kết hợp:

• tài liệu tham khảo sinh tự động;
• hướng dẫn viết tay;
• sidebar và điều hướng;
• versioning;
• tìm kiếm.

Phù hợp nhất cho: cổng thông tin tài liệu đầy đủ, tự lưu trữ, có versioning và hướng dẫn.

Giới hạn: đây là thiết lập nặng nhất trong danh sách vì bạn phải quản lý website React và build pipeline. Nếu chỉ cần một trang tham khảo, Redocly CLI đơn giản hơn.

Slate

Slate cung cấp bố cục tài liệu API ba cột quen thuộc:

• điều hướng bên trái;
• nội dung ở giữa;
• code sample bên phải.

Slate dùng giấy phép Apache 2.0 và chạy trên Middleman, nên cần Ruby toolchain. Khác với các công cụ trên, Slate không đọc trực tiếp OpenAPI. Bạn viết hoặc tạo Markdown trước, sau đó Slate kết xuất thành website tĩnh.

# Sau khi clone Slate fork và chạy bundle install
bundle exec middleman build

Lệnh này tạo website tĩnh trong thư mục build/. Một pipeline thực tế có thể là:

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

# 2. Kết xuất website Slate
bundle exec middleman build

Phù hợp nhất cho: tài liệu có cấu trúc tường thuật, được biên tập thủ công và tự lưu trữ hoàn toàn.

Giới hạn: repository gốc đã được lưu trữ dù vẫn có thể build và các fork vẫn hoạt động. Ruby dependency cũng nặng hơn một lệnh npx. Nếu tài liệu luôn được sinh trực tiếp từ spec, công cụ chuyển đổi chuyên dụng sẽ đơn giản hơn.

Apidog CLI: ghi chú minh bạch, không phải công cụ mã nguồn mở

Các công cụ phía trên giải quyết từng phần riêng: chuyển đổi spec, kết xuất tài liệu hoặc lưu trữ tệp tĩnh. Khi API của bạn là một dự án đang được duy trì với endpoint, schema và ví dụ, bạn cần tự ghép các bước này lại và giữ chúng đồng bộ.

Đây là khoảng trống mà apidog-cli hướng tới. Tuy nhiên, cần nói rõ: Apidog không phải mã nguồn mở. Đây là nền tảng freemium thương mại có gói miễn phí; CLI làm việc với dự án được lưu trữ thay vì chỉ với một file spec cục bộ.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

# Xuất Markdown
apidog export --project <projectId> --format markdown --output ./api-docs.md

# Xuất HTML
apidog export --project <projectId> --format html --output ./api-docs.html

Một lần export có thể chuyển dự án thành Markdown hoặc HTML mà không cần tự xây dựng chuỗi converter, renderer và hosting. Các lệnh apidog doc và apidog docs-site quản lý tài nguyên tài liệu từ script. Đầu ra có cấu trúc JSON, phù hợp để tích hợp vào CI hoặc agent.

Xem hướng dẫn đầy đủ về Apidog CLI để biết chi tiết về xác thực và từng nhóm lệnh. Nếu cần quy trình export Markdown, xem bài về trình tạo tài liệu API với tính năng xuất Markdown.

Ranh giới lựa chọn là:

• Mã nguồn mở: bạn sở hữu mã, tự lưu trữ tệp và không phụ thuộc nhà cung cấp.
• Apidog: quy trình tích hợp từ dự án được duy trì đến tài liệu có thể chia sẻ, đổi lại là phụ thuộc vào một nền tảng freemium được lưu trữ.

Cách lựa chọn

Đối chiếu giấy phép và định dạng đầu ra với những gì nhóm cần sở hữu.

Công cụ	Phù hợp nhất cho	Cài đặt	Mã nguồn mở?	Đầu ra
Redocly CLI	Một trang HTML hoàn chỉnh	npx @redocly/cli	Có — MIT, open core	HTML độc lập
Widdershins	Chuyển spec thành Markdown để commit	npm i -g widdershins	Có — MIT	Markdown
OpenAPI Generator	Tài liệu và SDK từ một công cụ	npm i -g @openapitools/openapi-generator-cli	Có — Apache 2.0	Markdown hoặc HTML
Swagger Codegen	Nhóm đã tiêu chuẩn hóa Swagger	npm i -g swagger-codegen-cli	Có — Apache 2.0	HTML
Docusaurus + plugin OpenAPI	Website tài liệu tự lưu trữ đầy đủ	npx create-docusaurus	Có — MIT	Website tĩnh
Slate	Tài liệu ba cột biên tập thủ công	Ruby + Bundler	Có — Apache 2.0	Website tĩnh
Apidog CLI	Xuất từ dự án đang được duy trì	npm i -g apidog-cli	Không — freemium	Markdown hoặc HTML

Tóm tắt lựa chọn:

• Dùng Redocly CLI khi cần tài liệu tham khảo HTML nhanh và có thể chia sẻ.
• Dùng Widdershins khi cần Markdown để version control.
• Dùng OpenAPI Generator khi đã tạo SDK và muốn tạo tài liệu từ cùng một toolchain.
• Dùng Swagger Codegen khi cần tiếp tục chuẩn hóa hiện có của Swagger.
• Dùng Docusaurus + plugin OpenAPI khi cần cổng thông tin có versioning và hướng dẫn.
• Dùng Slate khi cần kiểm soát biên tập cao cho tài liệu viết tay.
• Cân nhắc Apidog CLI khi nguồn dữ liệu là một dự án API được duy trì thay vì tệp đặc tả độc lập.

Để xem rộng hơn các lựa chọn miễn phí, bao gồm cả mã nguồn mở và freemium, xem các công cụ tài liệu API miễn phí.

Tổng kết

Việc chọn CLI tài liệu API mã nguồn mở phụ thuộc vào giấy phép, loại đầu ra và vị trí lưu trữ tài liệu. MIT và Apache 2.0 đều cho phép sử dụng, sửa đổi và tự lưu trữ mà không phát sinh phí chỗ ngồi.

Hãy chọn công cụ nhỏ nhất đáp ứng đầu ra cần thiết:

• Redocly CLI cho một trang HTML;
• Widdershins cho Markdown;
• OpenAPI Generator hoặc Swagger Codegen cho tài liệu đi cùng SDK;
• Docusaurus cho cổng thông tin;
• Slate cho website tài liệu được biên tập thủ công.

Nếu API nằm trong một dự án được duy trì thay vì file đặc tả rời rạc và bạn muốn xuất tài liệu thay vì nối nhiều công cụ, hãy tải xuống Apidog và thử apidog export. Bạn có thể đưa lệnh này vào CI để xây lại tài liệu mỗi khi API thay đổi, nhưng cần lưu ý đây là nền tảng freemium chứ không phải CLI mã nguồn mở.