Swagger là gì? Hướng dẫn cài đặt và sử dụng Swagger chi tiết nhất

Swagger là bộ công cụ xoay quanh OpenAPI Specification, giúp bạn mô tả, tạo tài liệu và kiểm thử REST API một cách nhất quán và tự động. Trong bài viết này, mình sẽ cùng bạn tìm hiểu chi tiết cấu trúc file, các thành phần chính trong hệ sinh thái Swagger, cách cài đặt, sử dụng và những lưu ý quan trọng khi đưa Swagger vào dự án.

Những điểm chính

• Khái niệm Swagger và OpenAPI: Hiểu rõ Swagger là một bộ công cụ và OpenAPI là một tiêu chuẩn, giúp bạn nhận biết vai trò của chúng trong việc thiết kế, tài liệu hóa và kiểm thử REST API.
• Các thành phần chính: Nắm vững các thành phần trong hệ sinh thái Swagger như UI, Editor, Codegen và SwaggerHub, giúp bạn hiểu rõ chức năng và cách chúng phối hợp để tạo nên một quy trình phát triển API toàn diện.
• Cấu trúc file Swagger: Nắm được cấu trúc của một file Swagger/OpenAPI, giúp bạn có thể tự tin đọc, hiểu và viết các file đặc tả API một cách chính xác.
• Lợi ích đối với nhà phát triển: Nhận thức được các lợi ích vượt trội từ việc tiêu chuẩn hóa, tự động hóa tài liệu đến hỗ trợ thiết kế API-first, giúp bạn hiểu rõ giá trị mà Swagger mang lại cho quy trình phát triển.
• Hướng dẫn cài đặt: Nắm vững quy trình 5 bước để cài đặt Swagger, giúp bạn có thể tự mình thiết lập môi trường và bắt đầu làm việc với các công cụ của Swagger.
• Hướng dẫn sử dụng: Biết thêm cách sử dụng SwaggerHub để thiết kế và khám phá API, giúp bạn áp dụng vào thực tế để quản lý và kiểm thử API một cách chuyên nghiệp.
• Lưu ý quan trọng: Nắm được các lưu ý và phương pháp hay nhất, giúp bạn sử dụng Swagger một cách an toàn, hiệu quả và tránh các sai lầm phổ biến khi triển khai trong môi trường sản xuất.
• Giới thiệu Vietnix: Biết đến Vietnix là nhà cung cấp hạ tầng uy tín, giúp bạn có một nền tảng tối ưu để triển khai các API và Swagger UI một cách an toàn, hiệu quả.
• Câu hỏi thường gặp: Được giải đáp các thắc mắc phổ biến liên quan đến Swagger.

Swagger là gì?

Swagger là một bộ công cụ mã nguồn mở xoay quanh OpenAPI Specification, dùng để thiết kế, mô tả, tạo tài liệu và kiểm thử các REST API. Thay vì phải viết tài liệu API thủ công, bạn mô tả API trong một file OpenAPI (YAML/JSON), Swagger sẽ dùng đặc tả này để sinh ra tài liệu tương tác, sinh code client/server và hỗ trợ quy trình phát triển API theo hướng “design first”.

Trong các dự án thực tế, Swagger thường được tích hợp sẵn vào ứng dụng (ví dụ qua Swagger UI trong ASP.NET Core, Spring Boot, NestJS,…) để đội ngũ dev, tester và đối tác truy cập tài liệu API thống nhất, cập nhật theo đúng phiên bản code đang chạy. Khi đặt API trên VPS hoặc server riêng, việc chuẩn hóa tài liệu với Swagger giúp việc debug, mở rộng tính năng và bàn giao giữa các nhóm trở nên rõ ràng và ít sai sót hơn.

OpenAPI là gì?

OpenAPI hay OpenAPI Specification (OAS) là một tiêu chuẩn dùng để mô tả REST API dưới dạng file máy có thể đọc được, thường ở định dạng JSON hoặc YAML. Một file OpenAPI đóng vai trò như hợp đồng kỹ thuật giữa các bên, mô tả đầy đủ endpoint, phương thức HTTP, tham số, body, response, mã lỗi và cơ chế xác thực của API mà không cần xem trực tiếp mã nguồn.

Cụ thể, một OpenAPI document cho phép bạn mô tả API theo các nhóm thông tin chính sau:

• Danh sách endpoints: Khai báo đầy đủ các đường dẫn API (ví dụ /users, /orders/{id}) và cách mỗi endpoint xử lý từng phương thức HTTP như GET, POST, PUT, DELETE.
• Cấu trúc request và response: Định nghĩa chi tiết tham số đường dẫn, query, header, cookie, schema dữ liệu vào/ra, mã trạng thái HTTP và các ví dụ minh họa.
• Bảo mật và metadata: Mô tả cơ chế xác thực (API key, OAuth2, JWT,…), thông tin liên hệ, license, điều khoản sử dụng và các thông tin chung khác của API.

Swagger UI

Swagger UI là công cụ hiển thị tài liệu API ở dạng giao diện web tương tác dựa trên file OpenAPI, giúp chuyển nội dung YAML/JSON khô cứng thành danh sách endpoint có thể click, xem tham số, schema và ví dụ request/response rõ ràng. Swagger UI còn cho phép gửi thử request trực tiếp lên API, rất hữu ích cho dev, QA và đối tác khi thử nghiệm nhanh mà không cần tự viết script gọi API.

Swagger Editor

Swagger Editor là trình soạn thảo giúp viết và chỉnh sửa file OpenAPI/Swagger ngay trên trình duyệt. Công cụ này hỗ trợ highlight cú pháp, gợi ý, validate theo chuẩn OAS và báo lỗi trực tiếp khi đặc tả sai cấu trúc. Nhờ đó team backend có thể thiết kế API theo hướng API-first rồi chia sẻ file OpenAPI cho frontend, mobile, QA và đối tác tích hợp.

Swagger Codegen

Swagger Codegen là công cụ tự động tạo mã nguồn (SDK client, server stub và tài liệu) từ các tệp đặc tả OpenAPI (Swagger). Công cụ này giúp rút ngắn thời gian phát triển, đảm bảo API và mã nguồn luôn đồng bộ, đồng thời hỗ trợ hơn 40 ngôn ngữ lập trình phổ biến như Java, Python, PHP, Nodejs,…

SwaggerHub

SwaggerHub là nền tảng hợp tác trực tuyến cho đội ngũ phát triển API dựa trên chuẩn OpenAPI. Nó kết hợp Swagger Editor, Swagger UI, Codegen, quản lý phiên bản, phân quyền, comment và tích hợp với Git để mọi thay đổi file OpenAPI được kiểm soát tập trung. Nhờ một không gian làm việc chung, dev, QA, kỹ thuật viết tài liệu và bên liên quan có thể cùng chỉnh sửa, review và xuất bản tài liệu API một cách có kiểm soát.

Metadata

Trong một file Swagger/OpenAPI, phần metadata thường nằm trong object info. Phần này mô tả thông tin chung về API như tên, mô tả ngắn, phiên bản, contact và license. Metadata giúp người dùng API hiểu nhanh họ đang làm việc với API nào, phiên bản nào và ai là đơn vị chịu trách nhiệm. Khi làm tài liệu cho nhiều môi trường hoặc nhiều service, metadata rõ ràng giúp tránh nhầm lẫn giữa các phiên bản và hệ thống.

Servers

Phần servers dùng để khai báo một hoặc nhiều URL nơi API được triển khai, ví dụ môi trường production, staging, development. Mỗi server có thể gồm URL, tên hiển thị và mô tả, từ đó client biết phải gửi request tới đâu. OpenAPI cho phép dùng biến trong URL server để linh hoạt với subdomain, port hoặc basePath, phù hợp với các hệ thống nhiều vùng hoặc nhiều khách hàng.

Ví dụ rút gọn:

servers:
  - name: Production
    url: https://api.example.com/v1
  - name: Staging
    url: https://staging-api.example.com/v1

Paths

Phần paths là nơi khai báo toàn bộ endpoint của API, mỗi key là một đường dẫn tương đối như /users hoặc /orders/{id}. Bên trong mỗi path, bạn định nghĩa các method như GET, POST, PUT, DELETE cùng với tham số, request body, response và mã trạng thái HTTP. Paths là nơi nhóm dev và client tập trung thời gian nhiều nhất, vì paths mô tả trực tiếp API có những chức năng gì và cách gọi chi tiết ra sao.

Ví dụ:

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: OK

Schema

Phần schema thường nằm dưới components.schemas và mô tả cấu trúc dữ liệu dùng cho request và response. Mỗi schema định nghĩa kiểu dữ liệu, thuộc tính, ràng buộc như required, format, enum giúp client và server thống nhất cấu trúc mang đi qua API. Khi tái sử dụng cùng một schema cho nhiều endpoint, file Swagger gọn hơn, dễ bảo trì và giảm nguy cơ sai lệch dữ liệu giữa các phần của hệ thống.

Ví dụ:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string

Lợi ích của Swagger với nhà phát triển API

Swagger mang lại nhiều lợi ích cho nhà phát triển API trong suốt vòng đời thiết kế, triển khai và bảo trì như:

• Tiêu chuẩn hóa cách mô tả API: Swagger dựa trên OpenAPI Specification, giúp toàn bộ team dùng chung một định dạng để mô tả endpoint, tham số, dữ liệu và mã phản hồi. Nhờ đó frontend, backend, QA và đối tác có cùng “ngôn ngữ” khi trao đổi về API.
• Rút ngắn thời gian viết tài liệu: Tài liệu được sinh tự động từ file OpenAPI thay vì viết tay trên wiki hoặc file riêng lẻ. Khi cập nhật API, bạn chỉ cần chỉnh file đặc tả, Swagger UI sẽ hiển thị tài liệu mới mà không phải chỉnh sửa ở nhiều nơi.
• Hỗ trợ thiết kế API-first: Nhà phát triển có thể bắt đầu từ file đặc tả, review với team, chốt hợp đồng API rồi mới triển khai code. Cách làm này giúp phát hiện lỗi thiết kế sớm và cho phép các team phát triển song song dựa trên một bản mô tả thống nhất.
• Tăng tốc kiểm thử và debug: Swagger UI cung cấp giao diện web để gửi request thử, xem request/response chi tiết và các mã lỗi mà không cần viết script hoặc dùng tool khác. Dev và QA có thể test nhanh theo từng endpoint, phát hiện lỗi mapping dữ liệu hoặc status code ngay trong giai đoạn phát triển.
• Giảm lỗi khi tích hợp đa ngôn ngữ: Với Swagger Codegen hoặc các generator tương tự, bạn sinh được client SDK và server stub cho nhiều ngôn ngữ dựa trên một file OpenAPI. Việc này giảm sai lệch giữa tài liệu và code, đồng thời giúp team sử dụng nhiều stack khác nhau vẫn bám đúng hợp đồng API.
• Cải thiện cộng tác nội bộ và với đối tác: Tài liệu API dạng tương tác giúp cả team dev, QA, technical writer và đối tác bên ngoài hiểu chính xác API đang cung cấp những gì. Việc on-board dev mới, mở API cho partner hoặc khách hàng bên ngoài cũng thuận tiện hơn vì chỉ cần chia sẻ một đường dẫn tài liệu Swagger.

Swagger có thể được cài đặt và sử dụng theo nhiều cách khác nhau, dưới đây là một quy trình đơn giản dựa trên Node.js, npm và Swagger UI/CLI.

Bước 1: Cài đặt Node.js và npm

Trước tiên, bạn cần cài Node.js (bao gồm npm – Node Package Manager) từ trang chủ https://nodejs.org/en/download và hoàn tất quá trình cài đặt trên hệ điều hành của mình. Sau khi cài xong, bạn có thể kiểm tra bằng lệnh node -v và npm -v trong Terminal hoặc Command Prompt để đảm bảo môi trường đã sẵn sàng.

Bước 2: Cài đặt Swagger CLI

Khi đã có npm, bạn có thể cài swagger-cli ở phạm vi global để dùng ở mọi thư mục. Mở Terminal hoặc Command Prompt và chạy:

npm install -g swagger-cli

Lệnh này sẽ cài công cụ dòng lệnh hỗ trợ validate, bundle và serve file Swagger/OpenAPI.

Bước 3: Tạo file swagger.yaml hoặc swagger.json

Tiếp theo, bạn tạo một file swagger.yaml hoặc swagger.json để mô tả API của mình. File này có thể được tạo thủ công hoặc khởi tạo từ mẫu có sẵn và chỉnh sửa dần (Bạn có thể tham khảo mẫu trên https://editor.swagger.io/).

Để thuận tiện, bạn có thể dùng Swagger Editor (bản online hoặc chạy local) để viết và chỉnh sửa file, vì editor có hỗ trợ highlight cú pháp, gợi ý và báo lỗi. Sau khi hoàn thành bản mô tả cơ bản, lưu file ở một đường dẫn dễ nhớ, ví dụ ./api/swagger.yaml.

Bước 4: Kiểm tra file Swagger bằng Swagger CLI

Khi đã có file mô tả, bạn dùng swagger-cli để kiểm tra tính hợp lệ của nó. Trong Terminal, di chuyển tới thư mục chứa file rồi chạy:

swagger-cli validate <path-to-swagger-file>

Trong đó <path-to-swagger-file> là đường dẫn tới file swagger.yaml hoặc swagger.json của bạn, ví dụ swagger-cli validate ./api/swagger.yaml. Nếu cấu trúc hợp lệ, công cụ sẽ trả về thông báo dạng is valid, nếu không sẽ hiển thị lỗi để bạn sửa ngay trong file.

Bước 5: Cài và chạy Swagger UI để xem tài liệu

Để hiển thị tài liệu API trên trình duyệt, bạn có thể cài Swagger UI và chạy local. Một cách đơn giản là dùng npm để cài swagger-ui-dist và phục vụ qua một HTTP server:

npm install -g http-server
npm install swagger-ui-dist

Sau đó, bạn tạo một file index.html tham chiếu tới swagger-ui-dist và trỏ đến URL file swagger của bạn, hoặc sử dụng repo Swagger UI chính thức:

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install
npm run dev

Khi server dev chạy, bạn mở trình duyệt và truy cập http://localhost:3200 (hoặc địa chỉ được log ra) rồi nhập URL tới file swagger.yaml/swagger.json của bạn để Swagger UI tải và hiển thị tài liệu.

Sử dụng SwaggerHub để thiết kế và quản lý API

Bước 1: Tạo tài khoản SwaggerHub

Bạn truy cập SwaggerHub và đăng ký tài khoản mới hoặc đăng nhập bằng tài khoản sẵn có như GitHub. Sau khi đăng nhập, bạn sẽ thấy dashboard hiển thị danh sách các API và project mà bạn đã tạo hoặc được chia sẻ.

Bước 2: Tạo API mới trên SwaggerHub

Tại dashboard, bạn chọn Create New và nhấn API để bắt đầu tạo một API mới. Bạn nhập các thông tin cơ bản như API Name, Version, Spec Format (OpenAPI 2.0 hoặc 3.x) rồi chọn Create API để hệ thống khởi tạo file đặc tả mẫu cho bạn.

Bước 3: Chỉnh sửa định nghĩa API với Swagger Editor tích hợp

Sau khi tạo API, SwaggerHub sẽ mở giao diện gồm hai phần: bên trái là Swagger Editor hiển thị mã YAML/JSON, bên phải là tài liệu API trực quan theo kiểu Swagger UI. Bạn chỉnh sửa nội dung trong editor (thêm paths, schemas, servers, security…) và quan sát sự thay đổi ở phần hiển thị tài liệu để đảm bảo API được mô tả đúng ý. Khi lưu lại, SwaggerHub tự quản lý version và lịch sử thay đổi của API.

Bước 4: Thử nghiệm API và đồng bộ với quy trình phát triển

Từ giao diện SwaggerHub, bạn có thể cấu hình server URL, thêm thông tin xác thực và sử dụng vùng Try it out để gọi thử các endpoint khi API backend đã sẵn sàng. Với các gói phù hợp, bạn có thể tích hợp SwaggerHub với Git, CI/CD hoặc tạo mock server để frontend và QA có thể làm việc từ sớm dù backend chưa hoàn thiện.

Bước 5: Chia sẻ và cộng tác trên API

SwaggerHub hỗ trợ chia sẻ API ở chế độ Public (ai cũng xem được) hoặc Private (chỉ người trong tổ chức hoặc nhóm có quyền). Bạn có thể mời thành viên vào organization, phân quyền thiết kế, review, chỉ đọc và dùng comment để trao đổi trực tiếp trên định nghĩa API, giúp việc cộng tác trở nên rõ ràng và có kiểm soát.

Sử dụng SwaggerHub Explore để khám phá và tạo tài liệu từ API có sẵn

Bước 1: Truy cập SwaggerHub Explore

Bạn mở trình duyệt và truy cập SwaggerHub Explore, đây là công cụ online cho phép tương tác với REST API và xem response trực tiếp mà không cần cài đặt thêm. Giao diện gồm vùng nhập URL, chọn phương thức HTTP, khu vực cấu hình header, query param và khu vực hiển thị phản hồi.

Bước 2: Nhập endpoint cần kiểm thử

Bạn nhập URL endpoint mà bạn muốn kiểm thử, ví dụ https://api.example.com/products, và chọn phương thức HTTP tương ứng như GET để lấy danh sách sản phẩm. Nếu API yêu cầu Authorization, bạn thêm header như Authorization: Bearer ngay trong giao diện Explore trước khi gửi request.

Bước 3: Gửi yêu cầu và xem phản hồi

Sau khi cấu hình xong, bạn nhấn Send để SwaggerHub Explore gửi request tới API. Kết quả trả về sẽ hiển thị ở phần Response, bao gồm status code, header và body, thường ở dạng JSON, giúp bạn kiểm tra nhanh cấu trúc dữ liệu và nội dung trả về.

Bước 4: Sinh định nghĩa OpenAPI từ API đang kiểm thử

Từ lịch sử các request đã gửi, bạn có thể yêu cầu công cụ sinh ra định nghĩa OpenAPI tương ứng với endpoint đó. Hệ thống sẽ phân tích URL, method, body và response để tạo cấu trúc OpenAPI ở dạng YAML hoặc JSON. Một ví dụ định nghĩa YAML đơn giản cho endpoint /products có thể trông như sau:

openapi: 3.0.0
info:
  title: Product API
  version: 1.0.0
paths:
  /products:
    get:
      summary: Get all products
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    price:
                      type: number

Bước 5: Xuất và tái sử dụng file OpenAPI

Sau khi hài lòng với phần mô tả, bạn có thể xuất file OpenAPI dưới dạng YAML hoặc JSON để chia sẻ cho team hoặc import vào SwaggerHub, Swagger UI và các công cụ khác. File này có thể dùng để sinh code client/server, tạo tài liệu tương tác, sinh test case tự động và tích hợp sâu hơn vào pipeline phát triển API.

Một số lưu ý khi sử dụng Swagger

Khi đưa Swagger/OpenAPI vào quy trình phát triển, bạn nên lưu ý một số điểm sau để tài liệu API dễ dùng và an toàn:

• Viết đặc tả đủ sâu, không chỉ liệt kê endpoint: Bạn cần mô tả đầy đủ schema request/response, tham số, mã phản hồi và ví dụ minh họa thay vì chỉ khai báo đường dẫn và method. Đặc tả chi tiết giúp sinh SDK, test tự động và tài liệu chính xác hơn, giảm việc phải đoán khi tích hợp.
• Giữ cấu trúc thống nhất trong toàn bộ file OpenAPI: Bạn nên tránh trùng lặp schema, đặt tên paths, field và model nhất quán để hạn chế technical debt trong tài liệu. Cấu trúc rõ ràng và đồng nhất giúp team mở rộng, refactor và tự động hóa (CI/CD, codegen, linting) thuận lợi hơn.
• Quản lý version API và version tài liệu rõ ràng: Bạn nên ghi rõ version trong info.version và cập nhật khi có thay đổi breaking. Khi cần tách biệt các phiên bản, bạn có thể dùng version trong URL như /v1, /v2 để không ảnh hưởng client đang sử dụng bản cũ.
• Không bỏ qua phần bảo mật trong spec: Bạn cần khai báo securitySchemes và gán vào từng endpoint hoặc toàn API để mô tả rõ cách xác thực (API key, OAuth2, JWT,…). Cách mô tả đầy đủ giúp dev tích hợp đúng cơ chế bảo mật và hỗ trợ các công cụ tự động kiểm tra rủi ro về truyền dữ liệu và phân quyền.
• Không public tài liệu Swagger của môi trường production một cách tùy tiện: Nếu bạn để Swagger UI và file OpenAPI truy cập công khai trên internet, attacker có thể dựa vào đó để dò endpoint và phương thức nhạy cảm. Bạn nên giới hạn truy cập Swagger trong môi trường thật bằng cơ chế xác thực, IP whitelist hoặc chỉ bật ở môi trường dev và staging.
• Tích hợp Swagger vào pipeline CI/CD thay vì cập nhật thủ công: Bạn có thể thêm bước validate OpenAPI và sinh tài liệu hoặc tệp HTML tự động mỗi lần build hoặc deploy. Cách vận hành này giúp tài liệu luôn khớp với code và giảm nguy cơ tài liệu lỗi thời so với API thực tế.

Vietnix – Nhà cung cấp hạ tầng triển khai API tối ưu cho Swagger

Khi đưa Swagger/OpenAPI vào dự án, hạ tầng ổn định và hiệu năng cao giúp bạn kiểm thử và triển khai API nhất quán ở mọi môi trường. Với dịch vụ VPS và thuê máy chủ tại Vietnix, bạn có thể chủ động cấu hình web server, reverse proxy và bảo mật để phục vụ cả API lẫn Swagger UI một cách tách biệt, hạn chế rủi ro truy cập trái phép. Để đạt hiệu suất tốt khi chạy API nhiều traffic, bạn có thể tham khảo các gói VPS NVMe hoặc dịch vụ thuê máy chủ Vietnix để tối ưu CPU, RAM và băng thông ngay từ đầu. Đội ngũ kỹ thuật Vietnix luôn sẵn sàng hỗ trợ bạn cấu hình môi trường chạy API và Swagger 24/7 theo nhu cầu thực tế.

Thông tin liên hệ:

• Website: https://vietnix.vn/
• Hotline: 1800 1093
• Email: sales@vietnix.com.vn
• Địa chỉ: 265 Hồng Lạc, Phường Bảy Hiền, Thành Phố Hồ Chí Minh

Swagger giúp bạn tiêu chuẩn hóa cách mô tả API, tự động hóa tài liệu và giảm sai lệch giữa thiết kế và triển khai trong suốt vòng đời phát triển dịch vụ. Khi kết hợp OpenAPI, Swagger UI, Swagger Editor, Swagger Codegen và SwaggerHub, bạn có thể xây dựng quy trình API-first rõ ràng, hỗ trợ tốt cho cả dev, QA và đối tác tích hợp. Nếu thiết kế đặc tả cẩn thận và gắn kết với pipeline CI/CD, Swagger sẽ trở thành nền tảng vững chắc để quản lý và mở rộng hệ thống API trong dài hạn.