“Swagger” có nghĩa là ba hoặc bốn thứ khác nhau, và đó là một nửa vấn đề. Đôi khi bạn muốn nói đến định dạng đặc tả mở. Đôi khi bạn muốn nói đến Swagger UI, trang hiển thị đặc tả đó thành tài liệu có thể nhấp. Đôi khi bạn muốn nói đến Swagger Editor, vùng văn bản trong trình duyệt nơi bạn viết YAML thủ công. Và đôi khi bạn muốn nói đến SwaggerHub, sản phẩm được lưu trữ tích hợp tất cả những thứ đó cho các nhóm. Khi một nhà phát triển tìm kiếm "swagger alternative" (thay thế swagger) trên Google, họ thường không hài lòng với một phần cụ thể nào đó: trình chỉnh sửa có cảm giác cồng kềnh, giao diện người dùng chỉ đọc, hoặc bộ công cụ chỉ dừng lại ở tài liệu và để việc kiểm thử cho một công cụ thứ hai hoàn toàn.
Khoảng trống cuối cùng đó là điều gây khó chịu. Bạn thiết kế một API trong Swagger Editor, hiển thị nó bằng Swagger UI, và sau đó mở một ứng dụng hoàn toàn riêng biệt để thực sự gửi yêu cầu, viết các khẳng định và chạy nó trong CI. Hai công cụ, hai nguồn sự thật, và một đặc tả dần dần khác biệt so với các bài kiểm thử. Nếu bạn đã chứng kiến tài liệu Swagger và Postman collections của bạn dần dần không đồng bộ, bạn sẽ hiểu được cái giá phải trả.
So sánh nhanh
| Công cụ | Thiết kế / chỉnh sửa đặc tả | Hiển thị tài liệu | Gửi yêu cầu + kiểm thử | Được lưu trữ cho nhóm | Giấy phép |
|---|---|---|---|---|---|
| Swagger (UI / Editor / Hub) | Có | Có | Không (UI chỉ để thử nghiệm) | SwaggerHub (có phí) | Apache 2.0 / thương mại |
| Apidog | Có (trực quan) | Có | Có (trình chạy kiểm thử đầy đủ + CLI) | Có | Bản miễn phí + có phí |
| Stoplight | Có (trực quan) | Có | Hạn chế | Có | Bản miễn phí + có phí |
| Redocly | Trình chỉnh sửa + CLI | Có (Redoc) | Không | Có | Bản miễn phí + có phí |
| Scalar | Trình chỉnh sửa | Có | Client API tích hợp sẵn | Có | Mã nguồn mở + có phí |
| Postman | Nhập đặc tả | Có | Có | Có | Bản miễn phí + có phí |
| Insomnia | Nhập đặc tả | Hạn chế | Có | Có | Bản miễn phí + có phí |
| Bump.sh | Không (tiêu thụ đặc tả) | Có | Không | Có | Bản miễn phí + có phí |
Các cột quan trọng nhất phụ thuộc vào vấn đề của bạn. Nếu việc hiển thị tài liệu là toàn bộ công việc, Redocly, Scalar và Bump.sh là những lựa chọn mạnh mẽ. Nếu bạn cần thiết kế và kiểm thử ở cùng một nơi, lựa chọn sẽ thu hẹp nhanh chóng.
Swagger làm tốt điều gì (và dừng lại ở đâu)
Hãy bắt đầu với phần trung thực. Đặc tả OpenAPI, phát triển từ đặc tả Swagger ban đầu, là tiêu chuẩn mà hầu hết mọi công cụ trong danh sách này đều đọc và viết. Swagger UI là trình hiển thị tài liệu API dễ nhận biết nhất trên thế giới, nó là mã nguồn mở theo giấy phép Apache 2.0, và nút “Try it out” đã giúp nhiều nhà phát triển làm quen với các cuộc gọi API trực tiếp hơn bất kỳ tính năng nào khác. Swagger Editor cung cấp cho bạn khả năng xác thực đặc tả tức thì khi bạn gõ. Không có điều nào trong số đó sẽ biến mất, và bạn không nên loại bỏ nó chỉ vì sự mới lạ.
Nơi nó dừng lại là vòng đời. Nút “Try it out” của Swagger UI chỉ gửi một yêu cầu duy nhất từ trình duyệt; đó là một bản demo, không phải là một bộ công cụ kiểm thử. Không có công cụ khẳng định, không có kịch bản kiểm thử, không có quản lý môi trường, không có trình chạy CLI cho CI. Swagger Editor là một hộp văn bản, vì vậy công việc thiết kế của bạn là viết YAML thủ công mà không có công cụ xây dựng lược đồ trực quan. SwaggerHub bổ sung tính năng cộng tác và lưu trữ nhưng tính phí theo từng chỗ ngồi, và ngay cả khi đó, kiểm thử không phải là nhiệm vụ của nó. Kết quả là một chuỗi công cụ tài liệu, chứ không phải chuỗi công cụ phát triển. Mọi lựa chọn thay thế dưới đây thực sự đang trả lời câu hỏi “tôi phải bổ sung cái gì, hoặc thay thế bằng cái gì, để vượt qua việc chỉ có tài liệu?”
Nếu bạn vẫn đang tìm hiểu về định dạng này, tài liệu giới thiệu về Swagger và OpenAPI là một điểm khởi đầu tốt hơn so với bài so sánh này.
1. Apidog: thiết kế và kiểm thử cùng một đặc tả ở một nơi
Apidog được xây dựng dựa trên ý tưởng rằng đặc tả, mock, các bài kiểm thử và tài liệu không bao giờ nên là các tệp riêng biệt trong các công cụ riêng biệt. Bạn thiết kế một endpoint trong một trình chỉnh sửa trực quan mà bên dưới sẽ viết OpenAPI hợp lệ, và ngay khi lược đồ tồn tại, bạn sẽ nhận được ba thứ miễn phí: một trang tài liệu tương tác, một máy chủ mock trả về dữ liệu có cấu trúc lược đồ, và một yêu cầu mà bạn thực sự có thể gửi và khẳng định.
Phần cuối cùng đó là điều làm nó khác biệt so với một công cụ tài liệu thuần túy. Swagger UI hiển thị cho bạn endpoint; Apidog cho phép bạn xây dựng kịch bản kiểm thử, xâu chuỗi các yêu cầu, trích xuất token từ một phản hồi và đưa nó vào yêu cầu tiếp theo, cũng như khẳng định các mã trạng thái và trường JSON mà không cần viết script. Khi thiết kế thay đổi, các bài kiểm thử vẫn trỏ đến cùng một định nghĩa, vì vậy chúng không âm thầm trở nên lỗi thời. Bạn có thể tạo một bộ test collections hoàn chỉnh trực tiếp từ một đặc tả OpenAPI thay vì xây dựng thủ công.
Đối với phía CI, có một trình chạy dòng lệnh được xuất bản dưới dạng gói npm apidog-cli. Bạn cài đặt nó và chạy một kịch bản đã lưu mà không cần giao diện:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Tham số -t là ID kịch bản kiểm thử, -e là ID môi trường và -r chọn định dạng báo cáo (ví dụ: cli hoặc html,cli). Trình chạy thoát với mã trạng thái sạch, vì vậy một khẳng định thất bại sẽ làm cho pipeline bị lỗi. Nếu bạn muốn biết mọi tham số, hãy chạy apidog run --help; hướng dẫn đầy đủ nằm trong hướng dẫn tự động hóa Apidog CLI và CI.
Phù hợp với: các nhóm đã chán việc thiết kế trong một công cụ và kiểm thử trong một công cụ khác. Không phù hợp với: nếu tất cả những gì bạn cần là một trang tài liệu tĩnh cho một đặc tả đã hoàn thành, Apidog là quá mức cần thiết. Tải xuống Apidog nếu việc trùng lặp giữa thiết kế và kiểm thử là vấn đề thực sự của bạn.
2. Stoplight: thiết kế ưu tiên đặc tả với quản trị chặt chẽ
Stoplight là đối thủ cạnh tranh gần nhất của Swagger Editor dành cho những người muốn thiết kế API trực quan thay vì gõ YAML. Trình chỉnh sửa Studio của nó cung cấp cho bạn chế độ xem tài liệu OpenAPI dựa trên biểu mẫu, và Spectral, công cụ linting mã nguồn mở của nó, thực sự là công cụ tốt nhất trong phân khúc để thực thi các hướng dẫn về phong cách API. Nếu tổ chức của bạn quan tâm đến việc đặt tên nhất quán, các mô tả bắt buộc và các quy tắc thiết kế trên hàng chục đặc tả, Spectral là lý do để xem xét Stoplight.
Những gì nó làm tốt: thiết kế trực quan, tạo mock từ đặc tả, tài liệu được lưu trữ và quản trị quy mô lớn. Những gì nó làm ít hơn: Stoplight là một nền tảng thiết kế và tài liệu, không phải là một trình chạy kiểm thử đầy đủ. Bạn có thể gọi mock, nhưng đối với việc kiểm thử chức năng nghiêm túc với các kịch bản chuỗi và khẳng định CI, bạn sẽ cần một công cụ khác. Các nhóm đã đầu tư vào Stoplight đôi khi kết hợp nó với một ứng dụng kiểm thử riêng biệt, điều này đưa bạn trở lại lãnh địa hai công cụ. Nếu bạn đang cân nhắc việc chuyển đổi, ghi chú di chuyển từ Stoplight sang Apidog sẽ đề cập đến những gì có thể chuyển đổi.
Phù hợp với: các nhóm lấy thiết kế làm trọng tâm với yêu cầu quản trị chặt chẽ. Không phù hợp với: nếu bạn muốn cùng một công cụ cũng chạy các bài kiểm thử của bạn.
3. Redocly: tài liệu tĩnh gọn gàng nhất, cộng với CLI thực thụ
Redocly được xây dựng dựa trên Redoc, trình kết xuất mã nguồn mở tạo ra các trang tài liệu tham chiếu API dài, ba bảng mà bạn đã thấy trên hàng trăm cổng dành cho nhà phát triển. Đầu ra sạch, nhanh và là một nâng cấp trực quan rõ rệt so với Swagger UI mặc định. Công ty Redocly bổ sung một cổng lưu trữ, quản lý phiên bản và một CLI thân thiện với nhà phát triển để đóng gói, lint và xem trước đặc tả của bạn từ terminal:
npx @redocly/cli lint openapi.yaml
npx @redocly/cli build-docs openapi.yaml -o docs.html
Những gì nó làm tốt: tài liệu. Nếu mục tiêu của bạn là xuất bản tài liệu tham chiếu API đẹp, hiệu suất cao từ một tệp OpenAPI, Redocly là một trong những lựa chọn mạnh mẽ nhất, và lệnh lint sẽ phát hiện các vấn đề về đặc tả sớm. Những gì nó không làm: gửi yêu cầu hoặc chạy kiểm thử. Nó hoàn toàn là một sản phẩm công cụ tài liệu và đặc tả. Để tìm hiểu sâu hơn về những ưu điểm và hạn chế của nó, hãy xem tổng hợp các lựa chọn thay thế Redocly.
Phù hợp với: các nhóm có nhu cầu hàng đầu là tài liệu tham chiếu được trau chuốt, có kiểm soát phiên bản. Không phù hợp với: bất kỳ ai mong đợi một lựa chọn thay thế cũng bao gồm kiểm thử.
4. Scalar: tài liệu mã nguồn mở với client API tích hợp sẵn
Scalar là lựa chọn mã nguồn mở mới hơn mà nhiều nhà phát triển tìm đến khi Swagger UI cảm thấy lỗi thời. Nó hiển thị một đặc tả OpenAPI thành một trang tài liệu sạch, có thể tìm kiếm, và không giống như Swagger UI, nó đi kèm với một client API thực sự được tích hợp vào tài liệu, vì vậy trải nghiệm “thử nghiệm” gần giống với một công cụ yêu cầu nhẹ hơn là một nút demo một lần. Bởi vì lõi được cấp phép MIT, bạn có thể tự lưu trữ và tùy chỉnh giao diện của nó một cách tự do.
Những gì nó làm tốt: tài liệu mã nguồn mở hấp dẫn với client tương tác, và chính sách miễn phí hào phóng. Những gì nó còn thiếu: nó không phải là một nền tảng kịch bản kiểm thử với các khẳng định, môi trường và trình chạy CI. Client tích hợp sẵn chỉ dành cho việc khám phá, không phải kiểm thử hồi quy tự động. So sánh các lựa chọn thay thế Scalar trình bày các đánh đổi so với các nền tảng nặng hơn.
Phù hợp với: các dự án mã nguồn mở và các nhóm độc lập muốn có tài liệu đẹp mắt mà họ kiểm soát. Không phù hợp với: các nhóm cần kiểm thử tự động trong một pipeline.
5. Postman: công cụ yêu cầu mà hầu hết các nhóm đã có
Postman không phải là một công cụ ưu tiên tài liệu, nhưng nó xuất hiện trong mọi tìm kiếm “swagger alternative” vì rất nhiều nhóm đã sử dụng nó. Bạn có thể nhập một đặc tả OpenAPI, lấy một bộ sưu tập các yêu cầu, gửi chúng, viết kiểm thử bằng JavaScript với API pm.test, và chạy toàn bộ trong CI với Newman. Đối với việc gửi yêu cầu và viết script thuần túy, nó đã trưởng thành và được hiểu rộng rãi.
Những gì nó làm tốt: các yêu cầu tùy chỉnh, linh hoạt trong viết script, một hệ sinh thái khổng lồ và không gian làm việc nhóm. Nơi phát sinh vấn đề: đặc tả và collection là các thành phần riêng biệt, vì vậy việc nhập một tệp OpenAPI được cập nhật không hợp nhất gọn gàng với các chỉnh sửa bạn đã thực hiện cho collection, và hai bên dần trở nên không đồng bộ. Giá cả cũng đã thúc đẩy các nhóm tìm kiếm các lựa chọn khác khi số lượng chỗ ngồi tăng lên. Nếu chi phí hoặc sự không đồng bộ là yếu tố thúc đẩy bạn, thì phân tích các lựa chọn thay thế Postman cho kiểm thử API là bài đọc liên quan.
Phù hợp với: các nhóm muốn tự do viết script tối đa và đã quen thuộc với Postman. Không phù hợp với: các nhóm muốn đặc tả và các bài kiểm thử là một nguồn sự thật đồng bộ duy nhất.
6. Insomnia: một client yêu cầu gọn nhẹ, mã nguồn mở
Insomnia là người anh em họ nhẹ hơn, thân thiện với bàn phím hơn của Postman. Nó nhập OpenAPI và GraphQL, gửi yêu cầu và hỗ trợ chế độ xem thiết kế để chỉnh sửa các đặc tả, với Inso CLI để chạy các bộ kiểm thử tự động. Các nhà phát triển thấy Postman nặng nề thường thích tốc độ và giao diện sạch hơn của nó, và lõi của nó có nguồn gốc mã nguồn mở thu hút những người lo ngại về sự phụ thuộc vào nhà cung cấp.
Những gì nó làm tốt: xử lý yêu cầu nhanh, hỗ trợ GraphQL và dấu chân đơn giản hơn. Các hạn chế: việc hiển thị tài liệu mỏng hơn so với các công cụ tài liệu chuyên dụng ở trên, và Insomnia đã có những bản phát hành gặp vấn đề về yêu cầu tài khoản và lưu trữ, điều này đã khiến một số người dùng đánh giá các lựa chọn khác. Nó gần hơn với “client yêu cầu với chế độ xem thiết kế” hơn là “nền tảng thiết kế và kiểm thử đầy đủ.” Để tìm hiểu thực tế, hãy xem cách sử dụng Insomnia để kiểm thử API.
Phù hợp với: các nhà phát triển muốn một client yêu cầu nhanh chóng, ít ma sát và không cần tài liệu được lưu trữ phong phú. Không phù hợp với: các nhóm cần thiết kế, tài liệu và kiểm thử được hợp nhất.
7. Bump.sh: tài liệu và theo dõi thay đổi, thực hiện theo một cách
Bump.sh cố tình làm một việc: nó biến một tệp OpenAPI hoặc AsyncAPI thành tài liệu được lưu trữ và theo dõi mọi thay đổi đối với đặc tả đó theo thời gian. Đẩy một phiên bản mới của đặc tả của bạn và Bump.sh tạo ra một changelog và diff dễ đọc, điều này thực sự hữu ích để thông báo các thay đổi gây phá vỡ cho người tiêu dùng API.
Những gì nó làm tốt: tài liệu được lưu trữ sạch sẽ và theo dõi thay đổi API hàng đầu, bao gồm cả cho các đặc tả AsyncAPI dựa trên sự kiện mà nhiều công cụ bỏ qua. Những gì nó không làm, một cách có chủ đích: nó không chỉnh sửa đặc tả, gửi yêu cầu hoặc chạy kiểm thử. Nó tiêu thụ một đặc tả mà bạn tạo ra ở nơi khác. Sự tập trung đó là một tính năng nếu tài liệu và changelog là nhu cầu của bạn, và là một yếu tố phá vỡ thỏa thuận nếu bạn muốn kiểm thử. Nếu bạn quan tâm đến sự phát triển của đặc tả, phân tích về những thay đổi giữa OpenAPI 3.0, 3.1 và 3.2 rất phù hợp với quy trình theo dõi thay đổi.
Phù hợp với: các nhóm xuất bản một đặc tả và cần tài liệu đẹp mắt cộng với một changelog đáng tin cậy. Không phù hợp với: bất kỳ ai muốn một công cụ thiết kế và kiểm thử tất cả trong một.
Cách chọn
Sắp xếp bảy công cụ theo công việc bạn thực sự cần làm.
- Chỉ tài liệu, từ một đặc tả đã hoàn thành. Redocly, Scalar và Bump.sh là những lựa chọn gọn gàng nhất. Chọn Redocly để có sự trau chuốt và CLI, Scalar để kiểm soát mã nguồn mở, Bump.sh để theo dõi thay đổi.
- Thiết kế đặc tả trực quan với quản trị. Stoplight, đặc biệt nếu linting của Spectral quan trọng đối với một tổ chức lớn.
- Gửi yêu cầu và viết script kiểm thử. Postman nếu bạn muốn tự do viết script tối đa, Insomnia nếu bạn muốn nó nhẹ hơn.
- Thiết kế và kiểm thử trong một nguồn sự thật duy nhất. Apidog, bởi vì đặc tả, mock, các bài kiểm thử và tài liệu chia sẻ một định nghĩa và các bài kiểm thử tương tự chạy trong CI thông qua
apidog-cli.
Một cách kiểm tra hữu ích: đếm các tab của bạn. Nếu việc thiết kế, tạo mock, lập tài liệu và kiểm thử một API đồng nghĩa với việc mở bốn công cụ khác nhau, thì sự khác biệt giữa chúng là một chi phí định kỳ, chứ không phải là một thiết lập một lần. Lý do “swagger alternative” là một tìm kiếm phổ biến như vậy là vì Swagger làm tốt phần việc của mình rồi dừng lại, và các công cụ bổ sung hiếm khi giao tiếp với nhau. Việc hợp nhất vòng lặp thiết kế-và-kiểm thử là nơi mà phần lớn thời gian tiết kiệm thực sự đến từ đó.
Bất kể bạn chọn công cụ nào, hãy giữ đặc tả ở trung tâm. Lint nó, xác thực nó và coi nó như một hợp đồng, chứ không phải là một suy nghĩ lại mà bạn tạo ra từ mã. Các nguyên tắc thiết kế API vững chắc và thói quen chạy một công cụ xác thực OpenAPI thực sự sẽ tồn tại lâu hơn bất kỳ công cụ nào trong danh sách này.
Câu hỏi thường gặp
Swagger có giống OpenAPI không? Không hoàn toàn. OpenAPI là tiêu chuẩn đặc tả; Swagger là tên gốc và tập hợp các công cụ (Swagger UI, Editor và SwaggerHub) được SmartBear xây dựng xung quanh nó. Khi mọi người nói “tệp swagger”, họ hầu như luôn muốn nói đến một tài liệu OpenAPI. Định dạng được chia sẻ, vì vậy mọi công cụ ở đây đều đọc cùng một đặc tả.
Giải pháp thay thế Swagger miễn phí tốt nhất là gì? Đối với tài liệu, Scalar là mã nguồn mở và miễn phí để tự lưu trữ. Đối với thiết kế và kiểm thử ở cùng một nơi, Apidog có gói miễn phí dành cho các nhà phát triển cá nhân và các dự án nhỏ. Bản thân Swagger UI và Swagger Editor cũng miễn phí và mã nguồn mở, vì vậy “miễn phí” hiếm khi là yếu tố quyết định; câu hỏi thực sự là công cụ đó bao gồm bao nhiêu phần của vòng đời.
Có công cụ nào trong số này có thể vừa thiết kế một đặc tả vừa chạy kiểm thử với nó không? Đây là điểm phân chia. Hầu hết các công cụ tài liệu (Redocly, Scalar, Bump.sh) chỉ hiển thị. Hầu hết các công cụ yêu cầu (Postman, Insomnia) chỉ kiểm thử, với đặc tả được nhập dưới dạng một thành phần riêng biệt. Apidog là lựa chọn được thiết kế để cùng một định nghĩa OpenAPI cung cấp sức mạnh cho thiết kế, mock và các kịch bản kiểm thử, và apidog-cli chạy các bài kiểm thử đó trong CI.
Tôi có phải từ bỏ Swagger UI để sử dụng một trong các công cụ này không? Không. Đặc tả OpenAPI có thể di động. Bạn có thể giữ Swagger UI cho tài liệu công khai và sử dụng một công cụ khác để thiết kế hoặc kiểm thử, hoặc nhập đặc tả hiện có của bạn vào một nền tảng mới và giữ một nguồn sự thật duy nhất. Vì định dạng là tiêu chuẩn, chi phí chuyển đổi chủ yếu liên quan đến thói quen làm việc, chứ không phải chuyển đổi tệp. Bạn thậm chí có thể nhập tệp Swagger hoặc OpenAPI và tạo các yêu cầu có thể chạy được trong vài phút.
Giải pháp thay thế nào tốt nhất cho các pipeline CI/CD? Bạn cần một công cụ có trình chạy kiểm thử thực thụ và một CLI trả về mã thoát phù hợp. Apidog cung cấp apidog-cli cho mục đích này; Postman có Newman và Insomnia có Inso. Các công cụ tài liệu thuần túy như Redocly và Bump.sh không được xây dựng để kiểm thử chức năng trong một pipeline, mặc dù CLI của Redocly hữu ích để linting các đặc tả như một bước pre-commit hoặc CI.