Redocly CLI là một công cụ tốt. Nếu bạn đã từng sử dụng nó để kiểm tra cú pháp (lint) các tệp OpenAPI, đóng gói một đặc tả đa tệp thành một, hoặc xây dựng tài liệu Redoc từ terminal, bạn đã biết điều đó. Vậy tại sao phải tìm kiếm một giải pháp thay thế Redocly CLI?
Thông thường, điều này liên quan đến hình dạng. Redocly CLI là một chuyên gia tập trung, ưu tiên mã nguồn: kiểm tra cú pháp, đóng gói, tách, ghép, xây dựng tài liệu. Điều đó hoàn toàn phù hợp với một số nhóm và không đủ cho những nhóm khác. Nếu bạn muốn một công cụ duy nhất cũng có thể thiết kế, mô phỏng và kiểm thử API của bạn, thì CLI không cố gắng trở thành công cụ đó, và nó cũng không nên.
Bài viết này nói về Redocly CLI (gói mã nguồn mở @redocly/cli), không phải sản phẩm tài liệu Redocly được lưu trữ. Nếu bạn đang so sánh nền tảng tài liệu được lưu trữ hoặc bản thân Redoc, hãy đọc tổng hợp các lựa chọn thay thế Redocly cho tài liệu API của chúng tôi. Bài viết này dành cho những người gõ redocly lint và redocly bundle và muốn biết những công cụ nào khác phù hợp với quy trình làm việc của họ.
Redocly CLI thực sự làm tốt những gì
Redocly CLI là mã nguồn mở và chạy trực tiếp trên terminal. Bạn cài đặt nó một lần và có được một bộ lệnh chặt chẽ thực hiện công việc của chúng một cách rõ ràng. Tài liệu Redocly CLI bao gồm tất cả chúng, nhưng đây là phiên bản ngắn gọn.
Kiểm tra cú pháp (Linting) là thế mạnh đặc trưng của nó. redocly lint xác thực mô tả OpenAPI, AsyncAPI, Arazzo hoặc Open-RPC của bạn và sau đó chạy các quy tắc hướng dẫn phong cách lên trên. Bạn cấu hình mọi thứ thông qua một tệp redocly.yaml: chọn một bộ quy tắc tích hợp sẵn (minimal, recommended, recommended-strict, hoặc spec) hoặc tự viết các quy tắc tùy chỉnh của riêng bạn. Quản trị dựa trên cấu hình đó khó có thể đánh bại nếu bạn muốn thực thi thiết kế API nhất quán trong CI trên nhiều nhóm.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Gom, tách và ghép xử lý việc quản lý đặc tả. redocly bundle theo dõi các con trỏ $ref và tạo ra một tệp hợp nhất. redocly split làm ngược lại, phân tách một mô tả duy nhất thành bố cục đa tệp. redocly join (thử nghiệm) hợp nhất nhiều tệp OpenAPI thành một.
redocly bundle openapi.yaml --output dist/openapi.json
Tài liệu đến từ build-docs. Nó tạo ra một trang HTML Redoc độc lập, và preview-docs cung cấp cho bạn bản xem trước trực tiếp cục bộ.
redocly build-docs openapi.yaml -o docs.html
Vì vậy, nếu nhu cầu của bạn là "xác thực theo hướng dẫn phong cách, đóng gói đặc tả và xuất tài liệu Redoc, tất cả từ terminal," thì Redocly CLI là một lựa chọn mặc định mạnh mẽ. Nhiều nhóm nên giữ nó. Lý do để tìm kiếm nơi khác là về phạm vi, không phải chất lượng.
Tại sao mọi người tìm kiếm một lựa chọn thay thế
Một vài mô hình xuất hiện lặp đi lặp lại:
- Bạn muốn một nền tảng tất cả trong một, không chỉ kiểm tra cú pháp và tài liệu. Redocly CLI không chạy kiểm thử API và không lưu trữ máy chủ mô phỏng. Nếu bạn cũng cần thiết kế, mô phỏng và công cụ chạy kiểm thử, bạn sẽ phải lắp ráp một chuỗi công cụ xung quanh nó.
- Bạn muốn có một giao diện người dùng đồ họa (GUI) bên cạnh CLI. Redocly được thiết kế ưu tiên mã nguồn. Nếu nhóm của bạn có những người thích làm việc trực quan, quản trị chỉ qua terminal là một điều khó chấp nhận.
- Bạn muốn một công cụ chạy kiểm thử tích hợp sẵn cho CI. Kiểm tra cú pháp (Linting) phát hiện các vấn đề về đặc tả. Nó không cho bạn biết liệu API đang chạy có hoạt động đúng không. Đó là một công cụ riêng biệt.
- Bạn không muốn ghép nối năm công cụ. Spectral để kiểm tra cú pháp, Redocly để đóng gói và tài liệu, Postman hoặc Newman để kiểm thử, một công cụ khác để mô phỏng. Điều đó hiệu quả, nhưng có rất nhiều thành phần cần duy trì.
Mỗi điểm đó chỉ ra một lựa chọn thay thế khác. Hãy cùng ghép chúng lại.
Danh sách rút gọn, theo những gì bạn thực sự muốn
Apidog, nếu bạn muốn một nền tảng duy nhất cho toàn bộ vòng đời API
Apidog là một nền tảng API tất cả trong một: thiết kế, mô phỏng, kiểm thử và tài liệu tại một nơi, với một CLI để nhập, xuất và chạy kiểm thử CI. Đây là lựa chọn đúng đắn khi bạn muốn có một công cụ duy nhất cho toàn bộ vòng đời thay vì ghép nối một công cụ kiểm tra cú pháp, một công cụ đóng gói, một công cụ chạy kiểm thử và một máy chủ mô phỏng.
Đây là phần trung thực. Apidog không có công cụ kiểm tra cú pháp hướng dẫn phong cách ưu tiên mã nguồn, có thể cấu hình với các bộ quy tắc tùy chỉnh như lint của Redocly. Không có lệnh apidog lint và không có cách nào để viết các quy tắc tùy chỉnh theo phong cách Spectral hoặc Redocly thông qua CLI. Apidog xác thực cấu trúc khi bạn nhập một đặc tả, nhưng nếu quản trị thiết kế chặt chẽ, có thể tùy chỉnh là điều duy nhất bạn quan tâm, Apidog sẽ không tự mình thay thế redocly lint. Hãy kết hợp nó với Spectral cho công việc đó. Chúng ta sẽ quay lại vấn đề này.
Những gì Apidog mang lại cho bạn mà Redocly CLI không có: một công cụ thiết kế trực quan, một máy chủ mô phỏng tích hợp sẵn, một công cụ xây dựng kiểm thử trực quan và một công cụ chạy kiểm thử CI. CLI xử lý các phần thuộc về terminal.
# Cài đặt và xác thực (token từ ứng dụng: avatar > Cài đặt tài khoản > API Access Token)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Nhập một đặc tả vào một dự án (xác thực + giải quyết các $ref đa tệp)
apidog import --project 123456 --format openapi --file ./openapi.json
# Xuất một tệp hợp nhất duy nhất và chọn phiên bản OpenAPI của bạn
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Chạy một kịch bản kiểm thử trong CI với nhiều định dạng báo cáo
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import thực hiện công việc xác thực khi nhập, và apidog export thực hiện công việc đóng gói khi xuất (nó xuất ra một tệp và có thể nâng cấp phiên bản OAS). Danh sách lệnh đầy đủ có trong tài liệu Apidog CLI, và hướng dẫn Apidog CLI đầy đủ của chúng tôi đi qua từng cờ. Phù hợp nhất cho: các nhóm muốn thiết kế, mô phỏng, kiểm thử và tài liệu dưới một mái nhà.
Spectral, nếu tất cả những gì bạn muốn từ Redocly là công cụ kiểm tra cú pháp
Nếu điều duy nhất bạn sử dụng là redocly lint, bạn không cần phải chuyển nền tảng. Spectral từ Stoplight là công cụ kiểm tra cú pháp (linter) mã nguồn mở, dựa trên quy tắc, trùng khớp trực tiếp nhất với tính năng kiểm tra cú pháp của Redocly. Bạn viết các quy tắc bằng YAML, chạy chúng đối với bất kỳ tài liệu OpenAPI hoặc AsyncAPI nào và tích hợp nó vào CI.
Công cụ kiểm tra cú pháp của Spectral và Redocly là những họ hàng gần. Cả hai đều dựa trên cấu hình, cả hai đều cung cấp các bộ quy tắc, cả hai đều cho phép bạn viết các quy tắc tùy chỉnh. Lựa chọn giữa chúng thường phụ thuộc vào sự phù hợp với hệ sinh thái và định dạng bộ quy tắc mà nhóm của bạn đã biết. Phân tích sâu của chúng tôi về kiểm tra cú pháp OpenAPI của Spectral bao gồm việc viết quy tắc, và hướng dẫn tổng quát hơn về kiểm tra cú pháp API so sánh bối cảnh kiểm tra cú pháp nếu bạn muốn có cái nhìn đầy đủ. Phù hợp nhất cho: các nhóm mà nhu cầu thực sự là kiểm tra cú pháp đặc tả thuần túy, có thể tùy chỉnh.
Scalar hoặc Bump.sh, nếu bạn chủ yếu muốn tài liệu
Nếu phần của Redocly CLI mà bạn quan tâm là build-docs, thì lựa chọn thay thế là một công cụ tài liệu, không phải một nền tảng. Scalar và Bump.sh đều biến mô tả OpenAPI thành tài liệu tham khảo được lưu trữ, có thể duyệt, mỗi công cụ có giao diện và bộ tính năng riêng. Chúng tập trung vào trải nghiệm tài liệu hơn là kiểm tra cú pháp hoặc kiểm thử. Phù hợp nhất cho: các nhóm có mục tiêu chính là tài liệu tham khảo API đẹp mắt, dễ bảo trì.
swagger-cli, không thực sự còn là một lựa chọn nữa
Bạn vẫn sẽ thấy swagger-cli được nhắc đến trong các hướng dẫn cũ, vì vậy cần phải rõ ràng: swagger-cli đã không còn được hỗ trợ. Kho lưu trữ GitHub của swagger-cli nói rằng nó không còn được duy trì và chỉ người dùng đến Redocly CLI như một công cụ kế nhiệm.
Nó chỉ từng có hai lệnh, swagger-cli validate và swagger-cli bundle. Nó chưa bao giờ kiểm tra cú pháp với các quy tắc phong cách, chưa bao giờ tạo tài liệu, chưa bao giờ chạy kiểm thử và chưa bao giờ mô phỏng bất cứ điều gì. Nếu bạn đang sử dụng nó hôm nay, hãy chuyển khỏi nó, chứ không phải chuyển đến nó. Hướng dẫn của chúng tôi về cách sử dụng swagger-cli bao gồm những gì nó đã làm, và Redocly thậm chí còn xuất bản một hướng dẫn di chuyển từ swagger-cli với ánh xạ cờ chính xác. Chúng tôi sẽ đưa ánh xạ đó vào dưới đây để hoàn thiện.
Bảng so sánh
Đây là cách các lựa chọn phù hợp với các công việc mà Redocly CLI xử lý. "Lint quy tắc tùy chỉnh" có nghĩa là một công cụ kiểm tra cú pháp (linter) hướng dẫn phong cách, ưu tiên mã nguồn, có thể cấu hình với các bộ quy tắc tùy chỉnh.
| Công cụ | Lint quy tắc tùy chỉnh | Đóng gói | Tài liệu | Mô phỏng | Kiểm thử | GUI | Mã nguồn mở | Phù hợp nhất cho |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Có | Có | Có (Redoc) | Không | Không | Không | Có | Quản trị lint, đóng gói và tài liệu ưu tiên mã nguồn từ terminal |
| Apidog | Không | Thông qua xuất | Có | Có | Có (CI runner) | Có | Không (freemium) | Một nền tảng duy nhất cho thiết kế, mô phỏng, kiểm thử và tài liệu |
| Spectral | Có | Không | Không | Không | Không | Không | Có | Kiểm tra cú pháp OpenAPI/AsyncAPI thuần túy, có thể tùy chỉnh |
| Scalar / Bump.sh | Không | Không | Có | Không | Không | Có | Khác nhau | Tài liệu tham khảo API được lưu trữ |
| swagger-cli | Không | Có | Không | Không | Không | Không | Có (không được hỗ trợ) | Không có gì mới, nó không được duy trì |
Một lưu ý về bảng: "Thông qua xuất" của Apidog có nghĩa là apidog export xuất ra một tệp hợp nhất, bao gồm lý do thực tế bạn sẽ chạy redocly bundle, nhưng nó không phải là lệnh bundle tương đương. Và Apidog là freemium, không phải mã nguồn mở, trong khi Redocly CLI và Spectral đều là mã nguồn mở. Hãy xem xét những đánh đổi đó.
Ánh xạ cờ đóng gói swagger-cli sang Redocly CLI
Nếu bạn đang dùng swagger-cli đã không còn được hỗ trợ và Redocly là điểm đến của bạn để đóng gói, các cờ ánh xạ rõ ràng:
| swagger-cli | Redocly CLI | Ý nghĩa |
|---|---|---|
-o, --outfile <file> |
--output (hoặc -o) |
Ghi vào một tệp thay vì stdout |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Loại tệp đầu ra |
-r, --dereference |
-d, --dereferenced |
Nhúng hoàn toàn tất cả các $ref |
Vì vậy, swagger-cli bundle -o output.json trở thành redocly bundle --output output.json.
Một khuyến nghị rõ ràng
Không có một người chiến thắng duy nhất, bởi vì câu trả lời đúng phụ thuộc vào công việc của Redocly CLI mà bạn đang cố gắng thay thế.
Hãy giữ Redocly CLI nếu quản trị của nó chính xác là những gì bạn cần. Một công cụ kiểm tra cú pháp, đóng gói và xây dựng tài liệu Redoc nhẹ, mã nguồn mở, dựa trên cấu hình mà bạn chạy hoàn toàn từ terminal là một thiết lập thực sự tốt. Không có lý do nào ở đây để từ bỏ một công cụ phù hợp.
Chọn Apidog nếu bạn mệt mỏi với việc lắp ráp một chuỗi công cụ và muốn thiết kế, mô phỏng, kiểm thử và tài liệu trong một nền tảng duy nhất với CLI cho các phần liên quan đến terminal. Bạn sẽ ngừng duy trì các công cụ riêng biệt cho từng giai đoạn và có được GUI cho những người trong nhóm của bạn muốn. Chỉ cần rõ ràng rằng bạn sẽ kết hợp nó với Spectral nếu bạn cũng cần kiểm tra cú pháp với quy tắc tùy chỉnh. Hướng dẫn Apidog CLI trong CI/CD cho thấy cách công cụ chạy kiểm thử khớp vào một pipeline, và Apidog CLI so với Newman so sánh nó với công cụ chạy mà nhiều nhóm đã sử dụng. Bạn có thể tải Apidog và dùng thử miễn phí, không yêu cầu thẻ tín dụng.
Chọn Spectral nếu kiểm tra cú pháp là toàn bộ mục đích. Đừng chuyển đổi nền tảng để thay thế một lệnh.
Sự thật thẳng thắn: Redocly là một chuyên gia CLI ưu tiên mã nguồn, và Apidog là một nền tảng trực quan tất cả trong một. Chúng là những mô hình khác nhau, không phải là một sự thay thế trực tiếp. Hãy chọn theo sự phù hợp.
Câu hỏi thường gặp
Apidog có phải là một công cụ thay thế trực tiếp cho Redocly CLI không? Không, và tốt hơn là nên thẳng thắn về điều đó. Apidog bao phủ nhiều giai đoạn hơn trong vòng đời (thiết kế, mô phỏng, kiểm thử, tài liệu) nhưng nó không có công cụ kiểm tra cú pháp với bộ quy tắc tùy chỉnh như redocly lint. Nếu quản trị đặc tả chặt chẽ, có thể cấu hình là công việc chính của bạn, hãy giữ công cụ kiểm tra cú pháp của Redocly hoặc sử dụng Spectral. Apidog thắng thế khi bạn muốn một công cụ duy nhất cho toàn bộ vòng đời API thay vì nhiều công cụ.
Apidog CLI có lệnh lint không? Không. Apidog xác thực cấu trúc khi bạn nhập một đặc tả với apidog import, nhưng không có lệnh apidog lint và không có cách nào để viết các quy tắc tùy chỉnh theo phong cách Spectral hoặc Redocly thông qua CLI. Để làm được điều đó, hãy kết hợp Apidog với Spectral.
Tôi có thể đóng gói một tệp OpenAPI mà không cần Redocly CLI không? Có. apidog export --project <id> --format openapi --output ./openapi.json xuất ra một tệp hợp nhất duy nhất và có thể nhắm mục tiêu một phiên bản OpenAPI cụ thể với --oas-version. Nó không phải là một lệnh bundle theo đúng nghĩa đen, nhưng nó đáp ứng cùng một nhu cầu thực tế. Nếu bạn chỉ muốn đóng gói và không muốn gì khác, redocly bundle vẫn là một lựa chọn tốt, tập trung.
Tôi có nên sử dụng swagger-cli vào năm 2026 không? Không. swagger-cli đã không còn được hỗ trợ và không được duy trì, và kho lưu trữ của chính nó chỉ đến Redocly CLI như một công cụ kế nhiệm. Nó chỉ từng xác thực và đóng gói. Hãy sử dụng Redocly CLI cho công việc đó, hoặc chuyển sang một nền tảng như Apidog nếu bạn cũng muốn phần còn lại của vòng đời.
Sự khác biệt giữa bài viết này và so sánh nền tảng tài liệu Redocly là gì? Bài viết này nói về công cụ mã nguồn mở @redocly/cli: kiểm tra cú pháp, đóng gói, tách, ghép và xây dựng tài liệu. Nếu bạn đang so sánh sản phẩm tài liệu Redocly được lưu trữ hoặc Redoc như một trình kết xuất tài liệu, hãy đọc các lựa chọn thay thế Redocly cho tài liệu API thay thế. Hai bài viết này bao gồm các sản phẩm khác nhau tình cờ có cùng tên. Đối với bản thân đặc tả, OpenAPI Specification là nguồn chân lý, và Redocly CLI trên npm là nơi bạn sẽ tìm thấy chi tiết cài đặt hiện tại.