Bạn có một tệp OpenAPI và muốn tạo tài liệu từ đó. Bạn không muốn thiết lập một dịch vụ, đăng nhập vào một cổng thông tin, hay thêm một bước xây dựng mà kéo theo một nửa npm. Bạn muốn một lệnh duy nhất đọc đặc tả và trả về một tệp Markdown hoặc một trang HTML duy nhất bạn có thể lưu trữ ở bất cứ đâu.
Đó là mục đích của danh sách này. Mọi công cụ ở đây đều nhỏ gọn: một binary duy nhất, một lệnh npx một dòng, hoặc một gói bạn cài đặt một lần và quên đi. Chúng khởi động nhanh, cần ít hoặc không cần cấu hình, và thực hiện công việc tài liệu mà không kéo theo một nền tảng đầy đủ. Một số tạo ra Markdown để bạn đưa vào một trang tài liệu hiện có. Một số tạo ra một tệp HTML độc lập. Tất cả chúng đều chạy trong CI và trong terminal, đó là điểm chính.
Nếu bạn muốn tìm hiểu rộng hơn về các nền tảng tài liệu, bài tổng hợp các công cụ tài liệu API REST hàng đầu bao gồm phần nặng về GUI. Bài viết này tập trung vào các công cụ ưu tiên terminal, có dung lượng nhẹ. Để có tài liệu tham khảo chính thức về những gì một trình tạo tài liệu đọc, Đặc tả OpenAPI là nguồn chân lý mà mọi công cụ dưới đây đều phân tích cú pháp.
Đ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 có nghĩa là yếu. Nó nói về dung lượng và độ phức tạp. Bốn yếu tố quyết định điều đó.
Kích thước cài đặt và các phụ thuộc. Một binary hoặc một gói npm tốt hơn một framework. Nếu việc tạo một trang tài liệu đòi hỏi cài đặt một runtime ngôn ngữ cộng với một bundler cộng với một hệ thống plugin, thì đó không phải là nhẹ, bất kể đầu ra trông như thế nào.
Khởi động và cấu hình. Những công cụ tốt nhất trong số này đọc đặc tả của bạn và tạo ra đầu ra mà không cần cấu hình gì. Bạn trỏ lệnh vào openapi.yaml và nhận lại một tệp. Bất kỳ công cụ nào cần một tệp cấu hình trước khi chạy đều mất điểm ở đây.
Đầu ra một mục đích. Mỗi công cụ dưới đây chỉ làm một việc: đặc tả vào, tài liệu ra. Markdown hoặc HTML, không có gì khác được gắn kèm. Đó là điều giúp chúng nhanh và dễ đoán trong một pipeline.
Chạy ở bất cứ đâu. Không có GUI, không đăng nhập đối với các công cụ mở, không có máy chủ để duy trì. Nó hoạt động trên máy tính xách tay của bạn và hoạt động theo cùng một cách trong một công việc CI. Để có nhiều lựa chọn miễn phí hơn, danh sách các công cụ tài liệu API miễn phí có các nền tảng; đây là phần CLI của danh sách đó.
Bây giờ là các công cụ, bắt đầu từ nhỏ nhất.
Widdershins
Widdershins nhỏ gọn nhất có thể. Nó là một gói npm duy nhất chuyển đổi tệp OpenAPI 3, Swagger 2 hoặc AsyncAPI thành Markdown. Đó là toàn bộ công việc. Nó không render một trang web hay chạy một máy chủ; nó trả cho bạn một tệp .md và hoàn thành nhiệm vụ.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Markdown mà nó tạo ra tương thích với Slate, điều này quan trọng nếu bạn định đưa nó vào một trang web tĩnh sau này. Các cờ hữu ích: --omitHeader loại bỏ phần tiêu đề YAML, và --language_tabs kiểm soát các ngôn ngữ mẫu code nào sẽ hiển thị.
Tốt nhất cho: đưa nội dung đặc tả vào Markdown mà bạn có thể commit, diff và đưa vào bất kỳ hệ thống tài liệu nào. Hạn chế rõ ràng: Markdown là tất cả những gì bạn nhận được. Không có kiểu dáng, không có bảng "thử ngay" tương tác và không có đầu ra được lưu trữ. Widdershins là một công cụ chuyển đổi, không phải một trình render, vì vậy bạn kết hợp nó với một cái gì đó biến Markdown thành một trang web.
OpenAPI Generator (các trình tạo tài liệu)
OpenAPI Generator nổi tiếng nhất với các SDK client, nhưng nó cũng đi kèm với các trình tạo tài liệu, và chúng rất tiện lợi khi bạn chỉ có một đặc tả. Trình tạo markdown viết một thư mục chứa Markdown; trình tạo html2 viết một trang HTML độc lập duy nhất. Bạn có thể điều khiển nó thông qua trình bao bọc npm mà không cần tự cài đặt Java.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Trình bao bọc npm vẫn tải xuống một tệp jar được hỗ trợ bởi JDK ẩn dưới, vì vậy nó nặng hơn Widdershins ở lần chạy đầu tiên. Sau đó, nó là một lệnh tạo một lần.
Tốt nhất cho: tái sử dụng một công cụ mà bạn có thể đã chạy cho SDK để cũng tạo tài liệu, với lựa chọn giữa Markdown và HTML độc lập. Hạn chế rõ ràng: đầu ra đơn giản và được điều khiển bằng template, và lần gọi đầu tiên kéo một tệp jar, vì vậy nó không thực sự là một binary duy nhất. Nếu bạn chỉ cần tài liệu và không có gì khác, các lựa chọn nhẹ hơn tồn tại.
Redocly CLI (build-docs)
Nếu bạn muốn một trang HTML độc lập, đẹp mắt từ một lệnh duy nhất, Redocly CLI là con đường ngắn nhất. Lệnh build-docs đóng gói đặc tả của bạn vào một tệp HTML độc lập được xây dựng trên Redoc. Không có máy chủ, không có bản dựng lưu trữ riêng; bạn nhận được một tệp có thể mở, gửi email hoặc đặt trên bất kỳ máy chủ tĩnh nào.
npx @redocly/cli build-docs openapi.yaml
Theo mặc định, nó ghi redoc-static.html. Thay đổi tên bằng --output:
npx @redocly/cli build-docs openapi.yaml --output api.html
Vì nó chạy qua npx, bạn thậm chí không cần cài đặt nó toàn cục để thử. Tốt nhất cho: một tài liệu tham khảo một trang được đánh bóng từ một lệnh duy nhất, với chủ đề mặc định rõ ràng và không cần quản lý vấn đề lưu trữ. Hạn chế rõ ràng: đầu ra là một tệp HTML, vì vậy nó là một trang tham khảo chứ không phải một cổng tài liệu nhiều trang, và các chủ đề và bản xem trước phong phú hơn nằm trong các gói trả phí của Redocly. Nếu bạn đang cân nhắc nó với các trình render tương tự, các so sánh các lựa chọn thay thế Redocly và các lựa chọn thay thế Scalar sẽ trình bày các đánh đổi.
Slate
Slate là trường hợp khác biệt ở đây: nó không phải là công cụ chuyển đổi đặc tả sang tài liệu, mà là một trình tạo trang web tĩnh cho các tài liệu API viết tay. Bạn viết Markdown, và Slate xây dựng bố cục tài liệu ba cột cổ điển (điều hướng, nội dung và các mẫu code cạnh nhau) thành một trang web tĩnh độc lập. Nó được hỗ trợ bởi Middleman, vì vậy nó cần Ruby.
# sau khi clone repo slate và cài đặt các phụ thuộc
bundle exec middleman build
Điều này tạo ra một trang web tĩnh hoàn chỉnh vào một thư mục build/ mà bạn có thể lưu trữ ở bất cứ đâu. Đây là nơi Widdershins phát huy tác dụng: tạo Markdown từ đặc tả của bạn, sau đó để Slate render nó, và bạn sẽ có nội dung dựa trên đặc tả trong bố cục của Slate.
Tốt nhất cho: tài liệu API được tuyển chọn thủ công, có tính kể chuyện, nơi bạn muốn kiểm soát biên tập đối với cấu trúc và văn phong. Hạn chế rõ ràng: đây là lựa chọn nặng nhất trong danh sách này vì nó cần một công cụ Ruby, và bản thân nó không đọc OpenAPI; bạn phải cung cấp cho nó Markdown. Nếu tài liệu của bạn được tạo trực tiếp từ một đặc tả và hiếm khi được chỉnh sửa thủ công, một công cụ chuyển đổi đơn thuần sẽ nhẹ hơn.
Apidog CLI (export + doc)
Các công cụ mã nguồn mở ở trên đều bao gồm một khía cạnh: chuyển đổi, render hoặc lưu trữ. Nếu API của bạn đã nằm trong một dự án thay vì một tệp YAML đơn lẻ, việc kết nối chúng lại với nhau sẽ gây ra khó khăn. Đó là nơi binary apidog-cli phát huy tác dụng. Đây là công cụ dòng lệnh đồng hành với Apidog, và một thao tác export sẽ biến một dự án thành Markdown hoặc HTML mà không cần pipeline xây dựng.
Cài đặt nó từ npm và xác thực bằng một token:
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Sau đó xuất tài liệu dự án sang Markdown hoặc HTML chỉ trong một lệnh:
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
CLI cũng quản lý trực tiếp các tài nguyên tài liệu. apidog doc xử lý các tài liệu Markdown của dự án, và apidog docs-site quản lý các trang tài liệu đã xuất bản, vì vậy bạn có thể liệt kê, tạo và cập nhật tài liệu từ một script hoặc công việc CI:
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
Đầu ra là JSON có cấu trúc, giúp dễ dàng chuyển tiếp vào các bước khác hoặc chuyển cho một agent. Để biết đầy đủ các lệnh, hướng dẫn đầy đủ về Apidog CLI sẽ hướng dẫn qua xác thực, dự án và từng nhóm lệnh.
Đây là một đánh giá trung thực. Apidog không phải là mã nguồn mở, và nó không phải là một binary đơn mục đích; nó là một nền tảng freemium, và CLI giao tiếp với một dự án được lưu trữ. Nó cũng không kiểm tra OpenAPI của bạn hay thực thi một hướng dẫn kiểu dáng; Redocly và Spectral làm điều đó. Điều mà CLI mang lại cho bạn là một lộ trình tích hợp từ một dự án API được duy trì đến Markdown hoặc HTML có thể chia sẻ, thay vì phải xâu chuỗi một công cụ chuyển đổi, một trình render và một máy chủ thủ công. Nếu bạn muốn đường dẫn xuất Markdown cụ thể, bài viết Trình tạo tài liệu API với xuất Markdown đi sâu hơn vào quy trình làm việc đó.
Cách chọn
Hãy chọn công cụ phù hợp với đị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 | Đặc tả sang Markdown, nhanh | npm i -g widdershins |
Có (MIT) | Markdown |
| OpenAPI Generator | 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 được tuyển chọn thủ công | Ruby + Bundler | Có (Apache 2.0) | Trang web tĩnh |
| Apidog CLI | Xuất từ một dự án đang hoạt động | npm i -g apidog-cli |
Không (phiên bản miễn phí) | Markdown hoặc HTML |
Phiên bản ngắn gọn: nếu bạn có một đặc tả thô và muốn Markdown để commit, hãy sử dụng Widdershins. Nếu bạn muốn một trang HTML có thể chia sẻ, redocly build-docs là nhanh nhất. Nếu bạn đang viết tài liệu thủ công và muốn một bố cục phù hợp, hãy dùng Slate. Và nếu API của bạn đã nằm trong một dự án và bạn muốn xuất cùng với quản lý tài liệu trong một CLI, hãy dùng Apidog. Để có cái nhìn tổng quan miễn phí, bài tổng hợp các công cụ tài liệu API miễn phí sẽ tổng hợp lại.
Tổng kết
Công cụ tài liệu nhẹ nhàng tuân theo một quy tắc: chọn thứ nhỏ nhất tạo ra đầu ra bạn cần. Widdershins và redocly build-docs bao gồm hầu hết các trường hợp từ đặc tả sang tài liệu chỉ trong một lệnh. OpenAPI Generator đáng giá khi bạn đã tạo SDK. Slate chỉ phát huy tác dụng với dung lượng lớn hơn khi bạn viết tài liệu bằng tay. Và khi API của bạn nằm trong một dự án thực tế thay vì một tệp rời rạc, tính năng xuất của apidog-cli sẽ cung cấp cho bạn Markdown hoặc HTML mà không cần một pipeline.
Nếu trường hợp cuối cùng là bạn, hãy Tải Apidog và thử apidog export đối với một dự án; nó sẽ dễ dàng tích hợp vào một công việc CI để tài liệu của bạn được xây dựng lại mỗi khi API thay đổi.