Nếu bạn đến đây sau khi chạy npm install -g @apidevtools/swagger-cli và nhận thấy các cảnh báo, đây là phiên bản tóm tắt: công cụ này không còn được duy trì nữa. Kho lưu trữ swagger-cli trên GitHub nêu rõ rằng nó đã lỗi thời, trích dẫn “gánh nặng bảo trì khi cố gắng theo kịp kỳ vọng của một lượng lớn người dùng nhưng có rất ít hoặc không có đóng góp nào.” Bản thân README đã chỉ bạn đến Redocly CLI như một công cụ kế nhiệm.
Vì vậy, bạn cần một công cụ thay thế. Điều này cụ thể nói về công cụ terminal swagger-cli, công cụ thực hiện validate và bundle. Nếu bạn thực sự muốn nói đến Swagger Editor, SwaggerHub, hoặc bộ thiết kế rộng hơn, hãy đọc 7 lựa chọn thay thế Swagger cũng kiểm thử API của bạn thay thế.
Hãy xem swagger-cli đã làm gì, sau đó chúng ta sẽ đi qua danh sách ngắn gọn những gì nên sử dụng bây giờ.
swagger-cli thực sự đã làm gì
Điều quan trọng là phải chính xác, vì công cụ thay thế phù hợp phụ thuộc vào những gì bạn đang sử dụng.
swagger-cli có chính xác hai lệnh:
# Xác thực định nghĩa Swagger 2.0 / OpenAPI 3.0 theo schema và kiểm tra $refs
swagger-cli validate openapi.yaml
# Theo dõi các con trỏ $ref và kết hợp một định nghĩa đa tệp thành một tệp duy nhất
swagger-cli bundle openapi.yaml -o bundled.json
Lệnh bundle có một tập hợp nhỏ các tùy chọn: -o/--outfile để ghi ra tệp, -t/--type để chọn JSON hoặc YAML, -r/--dereference để nhúng hoàn toàn mọi $ref, và -f/--format để định dạng lề.
Đó là toàn bộ công cụ. Nó xác thực cấu trúc và gộp các đặc tả đa tệp. Nó không thực hiện linting với các quy tắc kiểu dáng, tạo tài liệu, chạy kiểm thử hay giả lập bất cứ điều gì. Nếu bạn đọc những tuyên bố rằng swagger-cli "đã lint" đặc tả của bạn, thì chúng sai; nó chỉ kiểm tra định nghĩa của bạn theo schema OpenAPI và giải quyết các tham chiếu. Hãy ghi nhớ phạm vi đó, vì một số công cụ thay thế làm nhiều hơn thế rất nhiều, và bạn có thể muốn hoặc không muốn điều đó.
Danh sách ngắn
Ba công cụ bao gồm hầu hết mọi lý do bạn muốn sử dụng swagger-cli, cộng thêm một vài chuyên gia đáng được nhắc đến. Dưới đây là bản tóm tắt chân thực.
Redocly CLI: công cụ kế nhiệm chính thức và sự thay thế 1:1 gần nhất
Redocly CLI (@redocly/cli, nhị phân redocly) là mã nguồn mở và là công cụ mà README của chính swagger-cli đã giới thiệu. Redocly thậm chí còn xuất bản hướng dẫn di chuyển từ swagger-cli. Nếu mục tiêu của bạn là một trình xác thực và gộp terminal thay thế trực tiếp, hãy bắt đầu từ đây.
Cài đặt nó theo cách tương tự bạn đã cài swagger-cli:
npm install -g @redocly/cli@latest
# hoặc chạy mà không cần cài đặt
npx @redocly/cli@latest lint openapi.yaml
Việc ánh xạ rất rõ ràng. validate của swagger-cli trở thành redocly lint, kiểm tra đặc tả của bạn và áp dụng các quy tắc kiểu dáng có thể cấu hình. bundle của swagger-cli trở thành redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Dưới đây là bảng ánh xạ cờ bundle cạnh nhau:
| swagger-cli | Redocly CLI | Mục đích |
|---|---|---|
-o, --outfile |
--output (hoặc -o) |
Ghi ra một tệp |
-t, --type |
--ext (json, yaml, yml) |
Định dạng đầu ra |
-r, --dereference |
-d, --dereferenced |
Nhúng hoàn toàn tất cả các $ref |
Một điều cần biết: redocly lint làm được nhiều hơn validate của swagger-cli theo mặc định. Nó áp dụng một bộ quy tắc hướng dẫn kiểu dáng, không chỉ là kiểm tra schema. Nếu bạn muốn xác thực cấu trúc đơn giản mà swagger-cli cung cấp, hãy cấu hình redocly.yaml chỉ với quy tắc spec, sau đó chạy redocly lint openapi.yaml. Hành vi bộ quy tắc đó là điểm mạnh đặc trưng của Redocly hơn là một nhược điểm; đó là lý do tại sao các nhóm muốn quản lý dựa trên terminal lại thích nó. Bạn có thể điều chỉnh bộ quy tắc (minimal, recommended, recommended-strict, spec) hoặc viết các quy tắc tùy chỉnh. Xem thiết lập linter OpenAPI tốt nhất để biết cách nó phù hợp với các linter khác.
Redocly CLI cũng vượt xa hai lệnh của swagger-cli. Nó có thể split một mô tả duy nhất thành một cấu trúc đa tệp (ngược lại với bundle), join nhiều tệp (thử nghiệm) và xây dựng tài liệu HTML Redoc độc lập:
redocly build-docs openapi.yaml -o docs.html
Những gì nó không làm: chạy kiểm thử API hoặc lưu trữ máy chủ giả lập. Nó là một công cụ lint/bundle/docs ưu tiên code, dựa trên terminal, và là một công cụ xuất sắc. Nếu đó là tất cả những gì bạn cần, bạn có thể ngừng đọc và di chuyển ngay hôm nay.
Apidog: khi bạn muốn nhiều hơn validate cộng với bundle
Đây là sự định nghĩa lại chân thực. swagger-cli là một kịch bản tĩnh mà bạn chạy để xác thực và gộp. Nhưng đối với hầu hết các nhóm, việc xác thực và gộp chỉ là phương tiện để đạt được mục đích. Bạn xác thực để đặc tả là chính xác, bạn gộp để nó có thể di chuyển được, sau đó bạn giả lập nó, kiểm thử nó và lập tài liệu cho nó. swagger-cli đã giao những bước sau này cho các công cụ khác.
Apidog lấp đầy khoảng trống đó. Nó là một nền tảng API tất cả trong một: thiết kế, giả lập, kiểm thử và tài liệu trong một không gian làm việc duy nhất, với một CLI xử lý việc nhập, xuất và chạy kiểm thử CI. Trong khi swagger-cli cung cấp cho bạn một tệp, Apidog cung cấp cho bạn một không gian làm việc sống động được xây dựng từ tệp đó.
Hai lệnh ánh xạ trực tiếp nhất đến bộ nhớ cơ bắp swagger-cli của bạn là import và export. Cài đặt CLI và xác thực trước:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
Bạn lấy token từ ứng dụng hoặc web Apidog: avatar, sau đó Cài đặt Tài khoản, sau đó Mã truy cập API. Nó được lưu trữ trong ~/.apidog/config.toml, vì vậy đừng bao giờ in hoặc commit nó.
Import là bước xác thực của bạn. Nó đưa một định nghĩa vào một dự án và giải quyết các $ref đa tệp thành các tài nguyên hợp nhất. Nếu tệp bị lỗi định dạng, việc nhập sẽ làm nó lộ ra:
apidog import --project 123456 --format openapi --file ./openapi.json
Import chấp nhận một danh sách dài các định dạng ngoài OpenAPI, bao gồm Postman, HAR, Insomnia, WSDL và JSON Schema, rất tiện lợi khi các nguồn của bạn bị trộn lẫn.
Export là bước bundle của bạn, kèm theo một phần thưởng. Nó tạo ra một tệp hợp nhất duy nhất, và bạn chọn phiên bản OpenAPI khi xuất. Điều đó làm cho nó trở thành bundle cộng với một nâng cấp đặc tả tùy chọn trong một lệnh:
# Gộp và nâng cấp lên OpenAPI 3.1 trong một lần
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Hoặc xuất tài liệu HTML độc lập
apidog export --project 123456 --format html --output ./docs.html
Đối với CI, Apidog thêm bước mà swagger-cli chưa bao giờ có: chạy kiểm thử.
# 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"
# Hoặc chạy hoàn toàn offline từ một tệp bộ sưu tập đã xuất
apidog run ./collection.apidog-cli.json
CLI cũng quản lý trực tiếp các tài nguyên dự án, bao gồm endpoint, schema, mock, environment, branch, test-suite và test-report. Để biết chi tiết thiết lập và mọi cờ, hãy xem hướng dẫn đầy đủ về Apidog CLI và tài liệu Apidog CLI chính thức.
Bây giờ là những giới hạn trung thực, bởi vì sự phù hợp quan trọng hơn sự cường điệu. CLI của Apidog xác thực cấu trúc khi nhập, nhưng nó không cung cấp cho bạn một linter hướng dẫn kiểu dáng ưu tiên mã, có thể cấu hình với các bộ quy tắc tùy chỉnh như cách lint của Redocly làm. Không có lệnh apidog lint, và bạn không thể tạo các quy tắc tùy chỉnh theo kiểu Spectral thông qua CLI. Cũng không có split hoặc join. Apidog ưu tiên GUI: thiết kế, giả lập, xây dựng kiểm thử trực quan và tài liệu chủ yếu được tạo trong ứng dụng desktop hoặc web, với CLI xử lý việc nhập, xuất, chạy kiểm thử CI và quản lý tài nguyên đối với một dự án. Và Apidog là freemium, không phải mã nguồn mở, vì vậy nó là một mô hình khác so với Redocly CLI và Spectral.
Spectral: linting thuần túy, có thể tùy chỉnh trong CI
Nếu điều bạn thực sự muốn từ swagger-cli là xác thực nghiêm ngặt, có quy tắc trong quy trình của mình, thì linter chuyên dụng là Spectral từ Stoplight. Nó là mã nguồn mở và được xây dựng cho một nhiệm vụ: áp dụng một bộ quy tắc tùy chỉnh cho tài liệu OpenAPI (và các tài liệu JSON/YAML khác).
Spectral tỏa sáng khi bạn muốn thực thi kiểu dáng nội bộ dưới dạng mã, với các quy tắc riêng của bạn, trong mọi yêu cầu kéo. Nó không gộp, không tạo tài liệu và không kiểm thử các điểm cuối; nó chỉ lint. Kết hợp nó với một công cụ gộp và bạn đã xây dựng lại một phiên bản tập trung của những gì swagger-cli đã làm, cộng thêm quản trị thực sự. Hướng dẫn của chúng tôi về linting OpenAPI của Spectral sẽ hướng dẫn bạn viết các bộ quy tắc, và xác thực OpenAPI trong CI bao gồm việc kết nối nó vào một đường ống.
Tóm tắt: openapi-generator và vacuum
Hai công cụ nữa xuất hiện, vậy đây là phiên bản ngắn gọn, chính xác. openapi-generator là một trình tạo mã và client; nếu lý do bạn đóng gói là để cung cấp cho trình tạo, bạn có thể không cần bước đóng gói riêng biệt nào cả, vì nó tiêu thụ các đặc tả trực tiếp. vacuum là một linter OpenAPI nhanh, tương thích với Spectral được viết bằng Go, một lựa chọn tốt khi tốc độ lint trong các monorepo lớn là quan trọng. Cả hai đều không phải là một công cụ thay thế validate-plus-bundle chung, nhưng cả hai đều phù hợp với các nhu cầu cụ thể.
Bảng so sánh
Dưới đây là cách các tùy chọn được so sánh dựa trên các khả năng mà người dùng swagger-cli thường quan tâm.
| Công cụ | Xác thực | Gộp (Bundle) | Quy tắc Lint | Tài liệu | Giả lập (Mock) | Kiểm thử (Test) | Mã nguồn mở | Tốt nhất cho |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Có | Có | Không | Không | Không | Không | Có (lỗi thời) | Không có gì mới; nó không được duy trì |
| Redocly CLI | Có (lint) |
Có | Có (có thể cấu hình) | Có (HTML Redoc) | Không | Không | Có | Thay thế validate/bundle terminal trực tiếp với quản trị |
| Apidog | Có (khi nhập) | Có (khi xuất, với nâng cấp OAS) | Chỉ cấu trúc, không có bộ quy tắc tùy chỉnh | Có (ứng dụng + xuất) | Có | Có (chạy CLI) | Không (freemium) | Một công cụ cho toàn bộ vòng đời API |
| Spectral | Có (dựa trên lint) | Không | Có (bộ quy tắc tùy chỉnh) | Không | Không | Không | Có | Linting nghiêm ngặt, có thể tùy chỉnh trong CI |
| vacuum | Có (dựa trên lint) | Không | Có (tương thích Spectral) | Không | Không | Không | Có | Linting nhanh trên các đặc tả lớn |
Khuyến nghị
Đây không phải là tình huống "mọi thứ đều tuyệt vời, hãy chọn cái bạn thích". Hai lộ trình rõ ràng bao trùm hầu hết mọi người.
Chọn Redocly CLI nếu bạn muốn một sự thay thế trực tiếp. Đây là công cụ kế nhiệm chính thức, nó là mã nguồn mở và việc di chuyển gần như là cơ học: validate thành lint, bundle thành bundle, với bảng ánh xạ cờ ở trên. Nếu quy trình làm việc của bạn thực sự chỉ là "xác thực và đóng gói từ terminal," và bạn muốn thêm các quy tắc quản trị sau này mà không thay đổi công cụ, Redocly là lựa chọn rõ ràng. Nó giữ bạn ở chế độ ưu tiên code và dựa trên terminal, đó chính xác là nơi swagger-cli đã hoạt động.
Chọn Apidog nếu xác thực và đóng gói chỉ là bước khởi đầu. Hầu hết các nhóm không xác thực một đặc tả vì chính nó. Họ xác thực nó, sau đó ai đó cần một bản giả lập để xây dựng, người khác viết kiểm thử, và ai đó chịu trách nhiệm về tài liệu. swagger-cli dừng lại ở bước một và buộc bạn phải lắp ráp phần còn lại từ Spectral, một công cụ đóng gói, Postman và Newman. Apidog mang việc nhập (xác thực), xuất (đóng gói cộng với nâng cấp phiên bản OAS), giả lập, kiểm thử và tài liệu vào một không gian làm việc duy nhất, với một CLI cho các phần thuộc về CI. Bạn ngừng giám sát một kịch bản tĩnh, hiện không được duy trì và đưa toàn bộ đặc tả vào một nơi mà nó vẫn hữu ích sau khi được đóng gói.
Đây là những mô hình khác nhau, không phải các phiên bản cạnh tranh của cùng một thứ. Redocly CLI là chuyên gia nhẹ, hướng cấu hình mà bạn chạy hoàn toàn từ terminal. Apidog là nền tảng tất cả trong một mà tình cờ có một CLI mạnh mẽ. Hãy chọn dựa trên mức độ bạn muốn tích hợp vòng đời trong một công cụ, và hãy thành thật về điều đó: nếu bạn chỉ muốn lint và đóng gói trong terminal, Redocly gọn gàng hơn và miễn phí.
Nếu bạn muốn thử cách tiếp cận vòng đời, hãy tải xuống Apidog và nhập một đặc tả hiện có; nó miễn phí để bắt đầu, không yêu cầu thẻ tín dụng, và bạn có thể xem đầu ra được đóng gói, có phiên bản của mình trong vài phút.
Câu hỏi thường gặp
swagger-cli có còn được duy trì không?
Không. Kho lưu trữ GitHub của swagger-cli được đánh dấu là lỗi thời và không còn được duy trì, viện dẫn lý do đóng góp thấp so với lượng người dùng lớn. Nó vẫn cài đặt và chạy được, nhưng sẽ không nhận được bản sửa lỗi hoặc cập nhật, vì vậy hãy lên kế hoạch di chuyển.
Công cụ nào đã thay thế swagger-cli?
README của chính dự án chỉ đến Redocly CLI như một công cụ kế nhiệm. redocly lint thay thế swagger-cli validate và redocly bundle thay thế swagger-cli bundle. Redocly thậm chí còn xuất bản hướng dẫn di chuyển chuyên dụng. Nếu bạn muốn nhiều hơn validate và bundle, Apidog bao gồm import, export, mock, test và docs ở một nơi.
Apidog có miễn phí không?
Apidog là freemium. Có một gói miễn phí mà bạn có thể bắt đầu mà không cần thẻ tín dụng, với các gói trả phí dành cho các nhóm lớn hơn và nhu cầu nâng cao. Nó không phải là mã nguồn mở, đây là điểm khác biệt chính so với Redocly CLI và Spectral nếu cấp phép mở là một yêu cầu đối với bạn.
Tôi có thể giữ quy trình làm việc của swagger-cli y nguyên không?
Gần nhất là Redocly CLI. Để phản ánh validate cấu trúc đơn giản của swagger-cli, hãy thiết lập redocly.yaml chỉ với quy tắc spec và chạy redocly lint. Đối với việc đóng gói, các lệnh và cờ ánh xạ gần như một đối một. Để xem xét sâu hơn về phạm vi của công cụ gốc, hãy xem cách sử dụng swagger-cli từ terminal.