Apidog CLI vs Redocly CLI: Nên dùng CLI API nào?

Cả hai công cụ này đều hoạt động trong terminal của bạn, đều hỗ trợ OpenAPI, và đều xuất hiện khi một nhóm quyết định muốn có quy trình làm việc dòng lệnh cho các đặc tả API của mình. Đó là nơi sự trùng lặp kết thúc. Chúng giải quyết các vấn đề liền kề từ các hướng đối lập, và việc chọn sai công cụ có nghĩa là hoặc phải vật lộn với một linter không chạy thử nghiệm, hoặc phải tìm đến một nền tảng trong khi tất cả những gì bạn muốn chỉ là một kiểm tra cấu trúc nhanh chóng.

Đây là một so sánh trực tiếp, cấp độ lệnh giữa Apidog CLI và Redocly CLI. Không có lập luận sai lệch nào ở đây. CLI của Redocly thực sự là một phần mềm mã nguồn mở tốt, và bạn sẽ thấy chính xác những điểm mạnh của nó trước khi có bất kỳ phán quyết nào được đưa ra.

TL;DR: Kết luận

Chúng giải quyết các vấn đề trùng lặp nhưng khác nhau.

Redocly CLI (@redocly/cli, binary redocly) là một chuyên gia OpenAPI theo hướng "code-first": lint với các bộ quy tắc tùy chỉnh, đóng gói các spec nhiều tệp, tách và ghép chúng, và xây dựng tài liệu HTML độc lập. Nó là mã nguồn mở, định hướng cấu hình và hoạt động tự nhiên trong terminal. Nếu spec của bạn là nguồn đáng tin cậy và nằm trong git, thì đây là công cụ quản lý mà bạn chạy từ dòng lệnh.

Apidog CLI (apidog-cli, binary apidog) là giao diện dòng lệnh của một nền tảng API tất cả trong một. Nó nhập và xuất các định nghĩa dựa trên một dự án và chạy các kịch bản kiểm thử API trong CI với báo cáo JUnit và HTML. Nó xứng đáng có chỗ đứng khi cùng một spec cũng cần được giả lập (mock), kiểm thử và ghi tài liệu trong một không gian làm việc thay vì phải ghép nối từ các công cụ riêng biệt.

Hãy chọn Redocly CLI khi bạn muốn một công cụ nhẹ, mã nguồn mở để lint, đóng gói và tạo tài liệu mà bạn chạy hoàn toàn từ terminal. Hãy chọn Apidog khi bạn muốn có một công cụ duy nhất cho toàn bộ vòng đời API. Chúng cũng có thể hoạt động song song, và phần cuối cùng sẽ giải thích cách thức.

Hai triết lý khác biệt

Redocly CLI tập trung vào tệp và theo triết lý "code-first". Tài liệu OpenAPI trên đĩa là thứ bạn thao tác. Mỗi lệnh, redocly lint, redocly bundle, redocly build-docs, đều nhận một đường dẫn đến một tệp và thực hiện công việc của nó cục bộ, không cần tài khoản hay máy chủ. Hành vi được định hình bởi một cấu hình redocly.yaml mà bạn kiểm tra vào kho lưu trữ bên cạnh spec. Mô hình đó phù hợp với các nhóm coi mô tả API của họ như mã nguồn: được xem xét trong các pull request, được kiểm soát trong CI, được quản lý phiên bản như mọi thứ khác. Đặc tả OpenAPI là hợp đồng, và Redocly CLI là bộ công cụ để duy trì nó.

Apidog tập trung vào dự án và theo triết lý "platform-first". Bạn thiết kế các endpoint, xây dựng máy chủ mock và tạo các kịch bản kiểm thử một cách trực quan trong ứng dụng máy tính để bàn hoặc web, và CLI là giao diện không có giao diện người dùng (headless) cho một phần công việc đó. Hầu hết các lệnh CLI hoạt động trên một dự án Apidog trên máy chủ, được xác định bằng ID dự án và xác thực bằng mã truy cập. Spec không phải là một tệp rời rạc mà bạn lint tại chỗ; nó được nhập vào một không gian làm việc sống động, nơi nó cũng có thể được giả lập, kiểm thử và xuất bản thành tài liệu. Một môi trường, nhiều công việc.

Cả hai triết lý đều không sai. Chúng phù hợp với các nhóm khác nhau. Sự khác biệt trung thực là: Redocly cung cấp cho bạn một CLI tập trung, mã nguồn mở để quản lý spec, còn Apidog cung cấp cho bạn một CLI vào một nền tảng rộng lớn hơn.

Từng lệnh một

Đây là phần quan trọng, được ánh xạ từng nhiệm vụ. Mỗi lệnh dưới đây là thật; không có gì là bịa đặt.

Một vài hàng này đáng được ghi chú rõ ràng, bởi vì sự khác biệt là có thật và bài viết sẽ không trung thực nếu thiếu nó.

Linting là sân nhà của Redocly, không phải của Apidog. Redocly CLI lint các định dạng OpenAPI, AsyncAPI, Arazzo và Open-RPC theo các bộ quy tắc có thể cấu hình, và bạn có thể tự tạo quy tắc của riêng mình. Apidog kiểm tra cấu trúc của một định nghĩa khi bạn nhập nó, nhưng không có lệnh apidog lint, không có cấu hình kiểu redocly.yaml, và không có cách nào để viết các quy tắc hướng dẫn kiểu tùy chỉnh thông qua CLI. Nếu mục tiêu của bạn là một hướng dẫn kiểu "code-first" được thực thi trong terminal, Redocly là công cụ phù hợp. Apidog không cạnh tranh ở đây, và nói ngược lại sẽ là sai.

Tách và ghép thuộc về Redocly. redocly split phân tách một mô tả thành cấu trúc nhiều tệp, và redocly join (thử nghiệm) hợp nhất nhiều tệp thành một. Apidog không có cả hai lệnh này. Chức năng nhập của nó phân giải các $ref nhiều tệp thành tài nguyên hợp nhất, và chức năng xuất của nó tạo ra một tệp hợp nhất duy nhất, nhưng đó không giống như một tiện ích tách/ghép độc lập mà bạn chạy trên các tệp rời rạc.

Chạy kiểm thử và mock thuộc về Apidog. Redocly CLI không thực thi kiểm thử API và không lưu trữ máy chủ mock; đó là ngoài phạm vi thiết kế của nó. Apidog chạy các kịch bản kiểm thử không giao diện người dùng (headless) với apidog run và tạo ra các báo cáo JUnit, HTML, JSON và CLI cho pipeline của bạn, và mocking là một tính năng hàng đầu của nền tảng (được tạo trong ứng dụng, không điều khiển từ CLI).

Cả hai đều xây dựng tài liệu HTML từ terminal. redocly build-docs tạo ra một tệp HTML Redoc độc lập. apidog export --format html ghi một tệp tài liệu HTML từ dự án của bạn. Các công cụ khác nhau, cùng một kết quả trên terminal.

Các lệnh Redocly CLI thực tế

Cài đặt nó trên toàn hệ thống, hoặc bỏ qua việc cài đặt và chạy nó thông qua npx:

npm install -g @redocly/cli@latest
# hoặc, không cài đặt toàn cầu:
npx @redocly/cli@latest lint openapi.yaml

Lint một spec. Khi có tệp redocly.yaml, thao tác này sẽ áp dụng bộ quy tắc bạn đã chọn (minimal, recommended, recommended-strict, spec, hoặc các quy tắc tùy chỉnh):

redocly lint openapi.yaml

Nếu bạn chỉ muốn kiểm tra cấu trúc đơn giản, loại mà swagger-cli đã lỗi thời từng làm, hãy cấu hình redocly.yaml chỉ với quy tắc spec và chạy lệnh redocly lint tương tự. Redocly xuất bản hướng dẫn di chuyển từ swagger-cli vì Redocly CLI là công cụ kế nhiệm của nó. Kho lưu trữ swagger-cli hiện cũng có thông báo ngừng sử dụng vì lý do tương tự; công cụ cũ đó chỉ thực hiện xác thực và đóng gói, chứ chưa bao giờ lint theo các quy tắc kiểu.

Đóng gói một định nghĩa nhiều tệp thành một tệp duy nhất, theo dõi mọi $ref:

redocly bundle openapi.yaml --output bundled.json

Nếu bạn chuyển từ swagger-cli, các cờ lệnh ánh xạ rõ ràng: -o/--outfile trở thành --output, -t/--type trở thành --ext (json, yaml, hoặc yml), và -r/--dereference trở thành -d/--dereferenced.

Xây dựng tài liệu HTML độc lập với Redoc:

redocly build-docs openapi.yaml -o docs.html

Tách một mô tả duy nhất thành bố cục nhiều tệp, ngược lại với việc đóng gói:

redocly split openapi.yaml --outDir ./split-spec

Để có cái nhìn rộng hơn về cách Redocly so sánh với các công cụ khác trong danh mục này, hướng dẫn thiết lập OpenAPI linter so sánh Spectral, Redocly và Vacuum cạnh nhau, và tổng hợp các lựa chọn thay thế Redocly đề cập cụ thể đến nền tảng tài liệu.

Các lệnh Apidog CLI thực tế

Cài đặt CLI và xác thực bằng token từ ứng dụng (nhấp vào avatar, sau đó Account Settings, rồi API Access Token):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

Token sẽ nằm trong ~/.apidog/config.toml. Không in ra hoặc đưa vào commit.

Nhập một định nghĩa vào một dự án. Thao tác này kiểm tra cấu trúc và đưa nó vào, phân giải các $ref nhiều tệp thành tài nguyên hợp nhất:

apidog import --project 123456 --format openapi --file ./openapi.json

Chức năng nhập chấp nhận nhiều định dạng hơn OpenAPI: Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema và định dạng riêng của Apidog.

Xuất một tệp hợp nhất duy nhất, tùy chọn nâng cấp phiên bản OpenAPI. Đây là đóng gói cộng với một lần tăng phiên bản tùy chọn trong một bước:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Xuất tài liệu HTML trực tiếp từ dự án:

apidog export --project 123456 --format html --output ./docs.html

Chạy một kịch bản kiểm thử trong CI và xuất báo cáo mà pipeline của bạn có thể đọc:

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

Bạn cũng có thể chạy hoàn toàn ngoại tuyến từ một tệp bộ sưu tập đã xuất, không cần dự án hoặc token:

apidog run ./collection.apidog-cli.json

Toàn bộ tham chiếu cờ lệnh, bao gồm --out-dir, -n/--iteration-count, -d/--iteration-data, và --env-var, có trong hướng dẫn đầy đủ về Apidog CLI. Tài liệu Apidog CLI chính thức bao gồm cài đặt và mọi lệnh tài nguyên. Để so sánh CI giữa các runner, xem Apidog CLI vs Newman và Bruno CLI vs Apidog CLI.

Khi nào nên chọn Redocly CLI

Hãy tìm đến Redocly CLI khi spec là nguồn đáng tin cậy của bạn và bạn muốn quản lý nó như mã nguồn.

Bạn muốn một linter thực thụ với các quy tắc tùy chỉnh. Lệnh lint của Redocly và cấu hình redocly.yaml của nó là tính năng đặc trưng: chọn một bộ quy tắc tích hợp sẵn hoặc viết của riêng bạn, và thực thi các quy ước đặt tên, các trường bắt buộc và phong cách nội bộ trong mỗi commit. Không có gì trong CLI của Apidog có thể sánh được điều này. Nếu công việc là quản lý phong cách từ terminal, Redocly là câu trả lời.

Bạn muốn mã nguồn mở mà không cần tài khoản. CLI chạy hoàn toàn trên máy của bạn hoặc runner CI. Không cần đăng nhập, không token, không gọi máy chủ cho các lệnh lint, bundle, split, hoặc build-docs. Đối với các môi trường bị cô lập mạng (air-gapped) hoặc các quy tắc xử lý dữ liệu nghiêm ngặt, đó là một yêu cầu khó mà Redocly đáp ứng được, trong khi một CLI nền tảng thường không.

Bạn muốn một bộ công cụ nhẹ, tập trung. Nếu tất cả những gì bạn cần là lint, đóng gói, tách, ghép và tài liệu HTML từ terminal, Redocly làm chính xác điều đó và không hơn. Bạn có thể cài đặt hoặc chạy nó thông qua npx mà không cần thiết lập gì. Bộ lệnh đầy đủ có trong tài liệu Redocly CLI và trang gói npm.

Khi nào nên chọn Apidog

Hãy tìm đến Apidog khi spec là một phần của một vòng đời lớn hơn mà bạn không muốn phải lắp ráp từ các công cụ riêng biệt.

Bạn muốn thiết kế, mock, kiểm thử và tài liệu ở một nơi. CLI nhập spec của bạn, xuất một tệp hợp nhất sạch sẽ ở phiên bản OpenAPI bạn chọn và chạy các kịch bản kiểm thử trong CI. Cùng một dự án cũng cung cấp cho bạn thiết kế trực quan, một máy chủ mock và tài liệu đã xuất bản, tất cả đều chia sẻ một định nghĩa. Bạn không còn phải kết nối một linter, một công cụ mock, một trình chạy kiểm thử và một trình tạo tài liệu nữa.

Bạn muốn thực thi kiểm thử trong pipeline của mình với các báo cáo hữu ích. apidog run tạo ra JUnit XML cho bảng điều khiển CI của bạn, cộng với các artifact HTML và JSON, và thoát với mã lỗi khác 0 khi một kiểm thử thất bại. Redocly hoàn toàn không chạy kiểm thử, vì vậy nếu việc kiểm soát kiểm thử CI nằm trong danh sách của bạn, đây là nơi Apidog phù hợp. Các mẫu trong kiểm tra OpenAPI trong CI kết hợp tự nhiên với việc chạy kiểm thử trên cùng một pipeline.

Bạn muốn một nguồn thông tin đáng tin cậy duy nhất cho toàn bộ nhóm. Các tài nguyên nằm trong một dự án Apidog mà các nhà thiết kế, người kiểm thử và người viết đều làm việc trên đó. CLI là giao diện tự động hóa trên không gian làm việc chia sẻ đó, phù hợp với các nhóm muốn cộng tác trên một nền tảng hơn là chuyển các tệp spec qua lại.

Tải Apidog để cùng theo dõi. Nó miễn phí để bắt đầu, không yêu cầu thẻ tín dụng.

Chúng có thể bổ trợ cho nhau

Đây không hoàn toàn là "hoặc cái này, hoặc cái kia", và giả vờ như vậy sẽ bỏ lỡ thiết lập thực tế nhất.

Một quy trình làm việc mạnh mẽ sẽ chạy Redocly CLI (hoặc Spectral) làm cổng lint trong CI, thực thi hướng dẫn kiểu của bạn trên mỗi pull request, và sử dụng Apidog để thiết kế, mock, thực thi kiểm thử và tài liệu đã xuất bản. Lint ở nơi lint là tốt nhất, với các bộ quy tắc mã nguồn mở trong terminal. Mock, kiểm thử và ghi tài liệu ở nơi một nền tảng là tốt nhất. Spec chảy giữa chúng: lint tệp trong CI, nhập nó vào Apidog cho mọi thứ sau đó.

Sự kết hợp đó phát huy thế mạnh thực sự của mỗi công cụ thay vì buộc một công cụ phải làm công việc của công cụ kia.

Câu hỏi thường gặp

Apidog CLI có lệnh lint với các quy tắc tùy chỉnh như Redocly không?

Không. Apidog kiểm tra cấu trúc của một định nghĩa khi bạn nhập nó, nhưng không có lệnh apidog lint và không có cách nào để tạo các quy tắc hướng dẫn kiểu tùy chỉnh thông qua CLI. Để lint theo cấu hình, theo hướng "code-first", hãy sử dụng Redocly CLI hoặc Spectral.

Redocly CLI có thể chạy kiểm thử API trong CI không?

Không. Redocly CLI thực hiện lint, đóng gói, tách, ghép và xây dựng tài liệu. Nó không thực thi kiểm thử API và không lưu trữ máy chủ mock. Để chạy kiểm thử không giao diện người dùng (headless) với báo cáo JUnit và HTML, hãy sử dụng apidog run.

Apidog có phải là mã nguồn mở như Redocly CLI không?

Không. Redocly CLI và Spectral là mã nguồn mở. Apidog là freemium: CLI miễn phí để cài đặt từ npm, nhưng nó hoạt động dựa trên tài khoản và dự án Apidog chứ không phải là phần mềm mã nguồn mở hoàn toàn.

Tôi đã sử dụng swagger-cli để kiểm tra và đóng gói. Tôi nên chuyển sang công cụ nào?

Cả hai công cụ đều đáp ứng được. Redocly CLI là công cụ kế nhiệm của swagger-cli, với redocly lint (cấu hình quy tắc spec để kiểm tra đơn giản) và redocly bundle. Apidog cũng bao gồm các chức năng tương tự thông qua apidog import (kiểm tra) và apidog export (đóng gói, với tùy chọn nâng cấp phiên bản OpenAPI), và bổ sung thêm mock, kiểm thử và tài liệu trong cùng một không gian làm việc.