Khi bạn chọn một công cụ để tạo tài liệu API của mình, giấy phép là một phần của quyết định. Một trình tạo mã nguồn mở có nghĩa là bạn có thể đọc mã, tự lưu trữ đầu ra, phân nhánh nó nếu nó bị đình trệ và không bao giờ gặp giới hạn chỗ ngồi hoặc tường phí cho một tính năng bạn đã triển khai. Đối với một tác vụ chạy trong mọi bản dựng CI, điều đó quan trọng ngang với chất lượng đầu ra.
Danh sách này là 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ụ ở đây đều có sẵn mã nguồn theo giấy phép thực sự, MIT hoặc Apache 2.0, được lưu trữ trên GitHub và miễn phí để chạy mà không cần tài khoản. Bạn chỉ cần trỏ nó vào một tệp OpenAPI hoặc Swagger và nó sẽ cung cấp cho bạn Markdown, một trang HTML tĩnh hoặc một trang web tài liệu đầy đủ mà bạn sở hữu và tự lưu trữ.
Tôi sẽ gắn cờ giấy phép chính xác và câu chuyện tự lưu trữ cho từng công cụ, bởi vì đó là lý do bạn đang đọc một bài tổng hợp mã nguồn mở thay vì một bài tổng hợp chung. Nếu bạn muốn tìm hiểu rộng hơn, bài tổng hợp các công cụ tài liệu API REST hàng đầu cũng bao gồm các nền tảng GUI. Đặc tả OpenAPI là định dạng mà mọi công cụ dưới đây đều đọc, vì vậy một đặc tả hợp lệ là điểm khởi đầu của bạn.
Một lưu ý thành thật ngay từ đầu. Apidog xuất hiện gần cuối, và nó không phải là một mục mã nguồn mở; đó là một nền tảng freemium thương mại. Tôi chỉ đưa nó vào đây như một ghi chú bên lề được gắn nhãn cho trường hợp các công cụ mã nguồn mở còn thiếu sót, và tôi sẽ nói rõ về ranh giới đó.
Điều gì khiến một công cụ tài liệu CLI trở thành "mã nguồn mở"
Mã nguồn mở không chỉ có nghĩa là "miễn phí để tải xuống". Đối với công cụ tài liệu mà bạn sẽ tích hợp vào một bản dựng, ba điều quyết định liệu một công cụ có thực sự thuộc về bạn hay không.
Giấy phép thực sự. MIT hoặc Apache 2.0 có nghĩa là bạn có thể sử dụng, sửa đổi và phân phối lại công cụ một cách thương mại mà không cần xin phép. Cả hai đều được OSI chấp thuận. Apache 2.0 bổ sung một khoản cấp bằng sáng chế rõ ràng, điều mà một số nhóm pháp lý ưa thích. Mọi công cụ dưới đây đều mang một trong hai loại giấy phép này.
Đầu ra có thể tự lưu trữ. Mục đích của tài liệu mở là không có gì phụ thuộc vào máy chủ của nhà cung cấp. Các công cụ này tạo ra các tệp tĩnh: Markdown bạn commit, một trang HTML duy nhất hoặc một thư mục chứa HTML/CSS/JS. Bạn lưu trữ nó trên GitHub Pages, S3 hoặc một máy chủ Nginx đơn giản, và nó vẫn hoạt động cho dù dự án đằng sau công cụ có còn hoạt động hay không.
Bảo trì và cộng đồng. Mã nguồn có sẵn chỉ hữu ích nếu mã vẫn còn sống. Số sao, các commit gần đây và các vấn đề đang mở cho bạn biết liệu một fork có khả thi hay không nếu bạn cần. Một vài công cụ ở đây đã được lưu trữ nhưng vẫn hoạt động; tôi sẽ nói rõ điều đó.
Để có cái nhìn về các lựa chọn miễn phí trên cả mã nguồn mở và freemium, danh sách các công cụ tài liệu API miễn phí là tài liệu bổ sung. Bây giờ là các công cụ.
Redocly CLI
Redocly CLI là cách nhanh nhất để biến một đặc tả thành một tài liệu tham khảo HTML hoàn chỉnh, tự chứa. Nó được cấp phép MIT và là mã nguồn mở lõi (open core): CLI và công cụ kết xuất Redoc bên dưới nó là mã nguồn mở trên GitHub, trong khi một số tính năng cổng thông tin được lưu trữ nằm trong sản phẩm trả phí của Redocly. Lệnh build-docs hoàn toàn nằm trong phần mã nguồn mở.
npx @redocly/cli build-docs openapi.yaml -o api-docs.html
Lệnh đó tạo ra một tệp HTML duy nhất được xây dựng dựa trên Redoc. Mở nó cục bộ, đặt nó lên bất kỳ máy chủ tĩnh nào, hoặc đính kèm nó vào một bản phát hành. Không có gì gọi về nhà, và bạn có thể chạy nó ngoại tuyến sau khi gói đã được lưu vào bộ nhớ cache.
Tốt nhất ở: một tài liệu tham khảo API một trang sạch sẽ từ một lệnh duy nhất, được cấp phép MIT và tự lưu trữ. Giới hạn thành thật: đầu ra là một trang duy nhất, vì vậy nó là một tài liệu tham khảo chứ không phải một cổng thông tin nhiều trang, và các chủ đề phong phú hơn nằm ở cấp độ trả phí. Nếu bạn đang cân nhắc các công cụ kết xuất với nhau, so sánh các lựa chọn thay thế Redocly sẽ chỉ ra ranh giới mã nguồn mở nằm ở đâu.
Widdershins
Widdershins là một công cụ chuyển đổi thuần túy dưới giấy phép MIT. Nó đọc OpenAPI 3, Swagger 2 hoặc AsyncAPI và xuất ra Markdown; đó là toàn bộ công việc của nó. Vì đầu ra là Markdown thuần túy, bạn hoàn toàn sở hữu nó: commit nó, so sánh sự khác biệt trong một pull request, hoặc đưa nó vào bất kỳ trang web tĩnh nào bạn đang chạy.
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 giúp nó kết hợp gọn gàng với các trình tạo trang web sau này trong danh sách. Các cờ hữu ích: --omitHeader loại bỏ phần front-matter, và --language_tabs chọn các ngôn ngữ mẫu mã.
Tốt nhất ở: đưa nội dung đặc tả vào Markdown có thể kiểm soát phiên bản mà không bị khóa nhà cung cấp. Giới hạn thành thật: Markdown là tất cả những gì bạn nhận được. Không có kiểu dáng và không có trang web được kết xuất, vì vậy Widdershins là một nửa của một quy trình; một công cụ khác sẽ biến Markdown thành các trang.
OpenAPI Generator
OpenAPI Generator được cấp phép Apache 2.0 và được điều hành bởi cộng đồng, được phân nhánh từ Swagger Codegen vào năm 2018. Nó nổi tiếng nhất với các SDK client, nhưng nó cũng cung cấp các trình tạo tài liệu: trình tạo markdown tạo ra một thư mục Markdown, và html2 tạo ra một trang HTML tự chứa duy nhất.
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/
Giấy phép Apache 2.0 và khoản cấp bằng sáng chế của nó giúp các nhóm pháp lý cẩn trọng dễ dàng chấp thuận, và dự án này là một trong những dự án được duy trì tích cực nhất trong lĩnh vực này.
Tốt nhất ở: tái sử dụng một công cụ cho cả SDK và tài liệu, dưới một giấy phép dễ dãi với sự hỗ trợ mạnh mẽ từ cộng đồng. Giới hạn thành thật: trình bao bọc npm vẫn tải xuống một tệp jar Java trong lần chạy đầu tiên, vì vậy nó không phải là một tệp nhị phân duy nhất, và đầu ra được tạo mẫu thì đơn giản. Nếu bạn chỉ cần tài liệu, có những công cụ chuyển đổi nhẹ hơn tồn tại.
Swagger Codegen
Swagger Codegen là trình tạo dựa trên mẫu gốc từ nhóm Swagger, được cấp phép theo Apache 2.0. Nó có trước nhánh OpenAPI Generator và vẫn được duy trì bởi SmartBear. Đối với tài liệu, nó cung cấp hai lựa chọn: html cho một tài liệu tham khảo tĩnh một trang và dynamic-html cho một trang web tương tác nhỏ.
npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Hai dự án này có chung DNA và nhiều tùy chọn, vì vậy nếu nhóm của bạn đã tiêu chuẩn hóa trên bộ công cụ Swagger, điều này sẽ giữ bạn trong hệ sinh thái đó.
Tốt nhất ở: các nhóm đã đầu tư vào hệ sinh thái Swagger muốn tài liệu từ cùng một công cụ Apache 2.0 tạo ra các stub của họ. Giới hạn thành thật: nó được hỗ trợ bởi Java giống như OpenAPI Generator, và việc phát triển chậm hơn nhánh cộng đồng. Đối với hầu hết các thiết lập mới, OpenAPI Generator là lựa chọn tích cực hơn; Swagger Codegen thắng về tính liên tục.
Docusaurus với plugin OpenAPI
Nếu một trang HTML đơn lẻ không đủ và bạn muốn một trang web tài liệu thực sự, có phiên bản, Docusaurus là nền tảng mã nguồn mở. Nó được cấp phép MIT, được xây dựng bởi Meta và là một trong những trình tạo trang web tĩnh được sử dụng rộng rãi nhất trên web. Tự nó, nó kết xuất Markdown và MDX; plugin docusaurus-openapi-docs, cũng được cấp phép MIT và được duy trì bởi Palo Alto Networks, bổ sung chức năng tạo tài liệu từ đặc tả.
npx create-docusaurus@latest my-docs classic
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 đặc tả của bạn, gen-api-docs sẽ chuyển đổi tệp OpenAPI thành các trang MDX hiển thị bên trong trang Docusaurus, hoàn chỉnh với bảng "thử nghiệm" và điều hướng thanh bên.
Tốt nhất ở: một cổng thông tin tài liệu đầy đủ, tự lưu trữ với tính năng quản lý phiên bản, tìm kiếm và các hướng dẫn viết tay bên cạnh tài liệu tham khảo được tạo tự động. Giới hạn thành thật: đây là thiết lập nặng nhất ở đây. Bạn đang dựng một trang web React và một bước xây dựng, vì vậy nó quá mức cần thiết nếu tất cả những gì bạn cần chỉ là một trang tham khảo. Đối với trường hợp đó, Redocly CLI là con đường ngắn hơn.
Slate
Slate là bố cục tài liệu API ba cột cổ điển: điều hướng ở bên trái, văn bản ở giữa, các mẫu mã ở bên phải, tất cả đều được kết xuất dưới dạng một trang web tĩnh. Nó được cấp phép Apache 2.0 và được hỗ trợ bởi Middleman, vì vậy nó cần một bộ công cụ Ruby. Không giống như các công cụ chuyển đổi ở trên, Slate không đọc trực tiếp OpenAPI; bạn viết Markdown, và Slate sẽ kết xuất nó.
# after cloning your Slate fork and running bundle install
bundle exec middleman build
Lệnh đó tạo ra một trang web tĩnh hoàn chỉnh vào 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: chuyển đổi đặc tả của bạn thành Markdown, sau đó để Slate kết xuất nó thành bố cục quen thuộc đó.
Tốt nhất ở: tài liệu được tuyển chọn thủ công, mang tính tường thuật, nơi bạn muốn kiểm soát biên tập về cấu trúc và văn xuôi, trên một trang web tĩnh được tự lưu trữ hoàn toàn. Giới hạn thành thật: kho lưu trữ gốc đã được lưu trữ (người bảo trì đã ngừng hoạt động), mặc dù nó vẫn có thể xây dựng và các fork vẫn hoạt động, và phụ thuộc Ruby nặng hơn một lệnh npx duy nhất. Nếu tài liệu của bạn được tạo lại trực tiếp từ một đặc tả, một công cụ chuyển đổi sẽ nhẹ hơn.
Apidog CLI (ghi chú thành thật, không phải mục mã nguồn mở)
Các công cụ trên đều là mã nguồn mở, và mỗi công cụ bao gồm một phần: chuyển đổi, kết xuất, hoặc lưu trữ một tệp tĩnh. Khoảng trống mà chúng để lại là một dự án trực tiếp. Nếu API của bạn không phải là một tệp YAML đơn lẻ mà là một dự án được duy trì với các điểm cuối, lược đồ và ví dụ, bạn sẽ phải tự mình xâu chuỗi một công cụ chuyển đổi, một công cụ kết xuất và một máy chủ và giữ cho cả ba đồng bộ.
Đó là khoảng trống mà tệp nhị phân apidog-cli lấp đầy. Nói thẳng về giấy phép: Apidog không phải là mã nguồn mở. Đó là một nền tảng freemium thương mại với một gói miễn phí, và CLI giao tiếp với một dự án được lưu trữ chứ không phải một đặc tả cục bộ. Tôi chỉ đưa nó vào đây để so sánh trung thực về những gì các công cụ mã nguồn mở có thể và không thể làm, chứ không phải như một lựa chọn mã nguồn mở.
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
Một lần xuất sẽ biến dự án thành Markdown hoặc HTML mà không cần quy trình xây dựng, và apidog doc cùng apidog docs-site quản lý tài nguyên tài liệu từ một tập lệnh. Đầu ra là JSON có cấu trúc, vì vậy nó có thể được đưa vào CI hoặc một tác nhân một cách dễ dàng. Hướng dẫn đầy đủ về Apidog CLI trình bày chi tiết về xác thực và từng nhóm lệnh. Nếu quy trình xuất Markdown là điều bạn tìm kiếm, bài viết trình tạo tài liệu API với tính năng xuất Markdown sẽ đi sâu hơn.
Ranh giới nằm ở đâu: các công cụ mã nguồn mở cung cấp cho bạn mã bạn sở hữu, tệp bạn tự lưu trữ và không phụ thuộc vào nhà cung cấp. Apidog cung cấp cho bạn một lộ trình tích hợp từ một dự án được duy trì đến tài liệu có thể chia sẻ, với cái giá là một sản phẩm freemium được lưu trữ. Hãy chọn dựa trên việc nguồn đáng tin cậy của bạn là một đặc tả tĩnh hay một dự án trực tiếp.
Cách lựa chọn
Hãy đối chiếu giấy phép và đầu ra với những gì nhóm của bạn cần sở hữu.
| Công cụ | Tốt 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 | Đặc tả thành Markdown để commit | npm i -g widdershins |
Có (MIT) | Markdown |
| OpenAPI Generator | Tài liệu cộng SDK, một công cụ | npm i -g @openapitools/openapi-generator-cli |
Có (Apache 2.0) | Markdown hoặc HTML |
| Swagger Codegen | Các nhóm đã tiêu chuẩn hóa Swagger | npm i -g swagger-codegen-cli |
Có (Apache 2.0) | HTML |
| Docusaurus + plugin OpenAPI | Trang web tài liệu tự lưu trữ đầy đủ | npx create-docusaurus |
Có (MIT) | Trang tĩnh |
| Slate | Tài liệu ba cột được tuyển chọn thủ công | Ruby + Bundler | Có (Apache 2.0) | Trang tĩnh |
| Apidog CLI | Xuất từ một dự án trực tiếp | npm i -g apidog-cli |
Không (freemium) | Markdown hoặc HTML |
Tóm tắt: đối với một đặc tả cơ bản và một tài liệu tham khảo HTML có thể chia sẻ, hãy sử dụng Redocly CLI. Đối với Markdown bạn kiểm soát phiên bản, hãy dùng Widdershins. Nếu bạn đã tạo SDK, OpenAPI Generator cũng làm tài liệu, và Swagger Codegen sẽ hỗ trợ bạn nếu bạn đã tiêu chuẩn hóa trên Swagger. Khi bạn muốn một cổng thông tin thực sự với tính năng quản lý phiên bản và hướng dẫn, Docusaurus cộng với plugin OpenAPI là nền tảng mã nguồn mở, và Slate là lựa chọn cho tài liệu viết tay, được kiểm soát biên tập. Mọi công cụ này đều có sẵn mã nguồn và có thể tự lưu trữ, vì vậy không có gì bạn phát hành phụ thuộc vào việc nhà cung cấp vẫn kinh doanh. Để có cái nhìn rộng hơn về các lựa chọn miễn phí, bài tổng hợp các công cụ tài liệu API miễn phí tập hợp các lựa chọn mã nguồn mở và freemium lại với nhau.
Tổng kết
Việc chọn một CLI tài liệu mã nguồn mở phụ thuộc vào giấy phép, đầu ra và nơi tài liệu của bạn được lưu trữ. Cả MIT và Apache 2.0 đều cho phép bạn sử dụng, sửa đổi và tự lưu trữ mà không phải trả phí chỗ ngồi, vì vậy hãy chọn công cụ nhỏ nhất tạo ra đầu ra bạn cần: Redocly CLI cho một trang, Widdershins cho Markdown, OpenAPI Generator hoặc Swagger Codegen cho tài liệu bên cạnh SDK của bạn, Docusaurus cho một cổng thông tin, Slate cho các trang được tuyển chọn thủ công.
Nếu API của bạn nằm trong một dự án được duy trì thay vì một tệp rời rạc, và bạn muốn xuất tài liệu hơn là xâu chuỗi ba công cụ, hãy Tải xuống Apidog và thử apidog export đối với một dự án. Nó tích hợp vào một tác vụ CI để tài liệu của bạn được xây dựng lại mỗi khi API thay đổi, chỉ cần hiểu rõ rằng đó là một nền tảng freemium, chứ không phải một tệp nhị phân mã nguồn mở.