Swagger Client: Thư Viện OpenAPI Cho JavaScript

Swagger Client Là Gì?

Swagger Client là một module JavaScript, phát hành trên npm với tên swagger-client, dùng để tải một tài liệu Swagger 2.0 hoặc OpenAPI 3.x, resolve cấu trúc của nó, rồi gọi các operation mà nó định nghĩa. Dòng release 3.x hiện tại thay thế nhánh 2.x cũ và, theo README, thêm hỗ trợ OpenAPI 3.0 bên cạnh hỗ trợ Swagger 2.0 sẵn có; bản 3.37.x mở rộng hỗ trợ đó tới OpenAPI 3.2.0.

Năng Lực Chính Và Hỗ Trợ Specification

• ✓Đọc và resolve cả tài liệu Swagger 2.0 lẫn OpenAPI 3.x; dòng release 3.37.x hỗ trợ từ 3.0.0 đến 3.0.4, 3.1.0, và 3.2.0, theo bảng compatibility trong README.
• ✓Có tài liệu riêng cho Tags Interface, một HTTP client dựng riêng cho OAS operations, một module HTTP Client tổng quát khác, và một tài liệu API reference đầy đủ.
• ✓Có tài liệu OpenAPI Definition Resolver mô tả cách các con trỏ $ref và cấu trúc spec được resolve.
• ✓Chạy trên fetch gốc ở cả hai runtime — fetch có sẵn của Node.js 22+ và fetch riêng của từng trình duyệt — không kèm dependency HTTP nào khác.
• ✓Bản 2.1.32 đã đóng băng trên nhánh 2.x vẫn hỗ trợ các phiên bản spec Swagger 1.0, 1.1, và 1.2 cũ hơn.
• ✓Một migration guide riêng cùng tài liệu 'graveyard' nêu rõ những gì đã thay đổi và bị bỏ giữa 2.x và 3.x.

Bắt Đầu Với Swagger Client

README không nêu trực tiếp lệnh cài đặt — nó trỏ tới docs/usage/installation.md như hướng dẫn cài đặt thật sự, nên hãy coi file đó là nguồn chính xác. Điều README xác nhận trực tiếp: tên package được publish là swagger-client, cần Node.js từ 22 trở lên vì Swagger Client dựa vào fetch gốc của Node, còn Node 12, 14, 16, 18, và 20 đã hết vòng đời và không còn được hỗ trợ. Việc cài package cũng chạy Scarf, thứ thu thập dữ liệu sử dụng lúc cài đặt mà README gọi là anonymized; tắt nó bằng cách đặt scarfSettings.enabled thành false trong package.json, hoặc chạy install với SCARF_ANALYTICS=false.

Tương Tác Với Tài Liệu OpenAPI

Code sử dụng thực tế không nằm trong nội dung README — nó dẫn tới năm tài liệu riêng: Tags Interface, HTTP client cho OAS operations, OpenAPI Definition Resolver, một tài liệu HTTP Client tổng quát, và tài liệu Swagger Client API reference đầy đủ. Đọc tài liệu resolver cùng tài liệu OAS-operations client, có thể thấy cách làm là resolve cấu trúc tài liệu như một bước, rồi gọi các RESTful services mà nó mô tả như một bước riêng, thay vì gộp vào một lệnh gọi duy nhất. Trình duyệt được hỗ trợ gồm Chrome, Safari, Firefox, Edge bản mới nhất, mỗi trình duyệt dùng fetch gốc riêng. Không kèm polyfill nào.

Các Thư Viện OpenAPI Client Khác

Câu Hỏi Thường Gặp

Vấn đề Swagger Client giải quyết

Một tài liệu OpenAPI mô tả hình dạng của một API trên giấy, nhưng vẫn cần thứ gì đó tải file YAML hay JSON đó, resolve các con trỏ $ref thành một cấu trúc dùng được, rồi để JavaScript gọi các operation mà nó định nghĩa. Swagger Client tồn tại cho đúng khoảng trống đó: biến một tài liệu Swagger 2.0 hoặc OpenAPI 3.x thành các định nghĩa API đã resolve, gọi được ngay trong ứng dụng Node.js hoặc trình duyệt, thay vì để nhà phát triển tự parse spec bằng tay.

Trường hợp sử dụng tốt nhất

• •Gọi các operation trên một backend được mô tả bằng OpenAPI từ ứng dụng Node.js hoặc trình duyệt, dùng HTTP client cho OAS operations thay vì tự viết fetch wrapper cho từng endpoint.
• •Resolve cấu trúc $ref của một tài liệu OpenAPI lớn bằng code, qua OpenAPI Definition Resolver, thay vì tự viết logic theo dõi $ref.
• •Dùng chung một codebase client giữa service Node.js và bundle trình duyệt, vì cả hai đều chạy trên fetch gốc thay vì một thư viện HTTP riêng cho từng runtime.
• •Làm việc với một spec Swagger 2.0 chưa chuyển sang OpenAPI 3.x — dòng 3.x hiện tại vẫn liệt kê hỗ trợ 2.0 trong bảng compatibility.
• •Migrate một tích hợp 2.x cũ sang 3.x, dùng migration guide riêng và tài liệu graveyard làm tham chiếu cho những gì đã mất.

Ai nên dùng — và ai nên bỏ qua

Hãy dùng Swagger Client nếu bạn viết JavaScript để làm việc với một spec Swagger 2.0 hay OpenAPI 3.x và muốn tải, resolve, rồi gọi các operation của nó từ code, trong Node.js hay trình duyệt, mà không cần generate một SDK có type trước. Bỏ qua nếu bạn muốn type ở compile-time từ spec của mình — Swagger Client đưa cho bạn dữ liệu spec đã resolve và một client để gọi operation, không phải TypeScript được generate sẵn — hoặc nếu ngưỡng Node.js 22+ mà dòng 3.x hiện yêu cầu là rào cản với dự án của bạn.

Repo liên quan