Swagger là gì? Hướng dẫn Sử dụng Swagger cơ bản

Trong bài viết này mình sẽ giới thiệu tổng quan về công cụ Swagger, nó cung cấp những tính năng hữu ích nào, sử dụng Swagger như thế nào để đạt hiệu quả cao trong công việc.

Hướng dẫn cài đặt và cách viết Document chuẩn cho API bằng Swagger, Postman các bạn có thể tham khảo tiếp tại bài viết API Document là gì? Hướng dẫn viết Document chuẩn cho API

1. OpenAPI là gì?

OpenAPI là một chuẩn dùng để mô tả các API (giao diện lập trình ứng dụng) dựa trên giao thức HTTP, thường là kiểu API RESTful.

Với OpenAPI, bạn có thể viết ra mô tả của API dưới dạng file YAML hoặc JSON. File này sẽ chứa thông tin về những gì API nhận (đầu vào) và trả về (đầu ra). Nó cũng có thể bao gồm thông tin về nơi API được lưu trữ, các yêu cầu để truy cập API (như cấp quyền), và các chi tiết khác mà người dùng API (VD: các nhà phát triển web) cần.

openapi: 3.0.0
info:
  title: Dog API
  version: 1.0.0
servers:
- url: https://dog.ceo/api
paths:
  /breed/{breedName}/images:
    get:
      description: Get images of dog breeds
      parameters:
      - in: path
        name: breedName
        schema:
          type: string
          example: hound
        required: true
      responses:
        '200':
          description: A list of dog images
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: array
                    items:
                      type: string

Định nghĩa API có thể được viết bằng tay, tạo ra bằng công cụ, hoặc tự động sinh ra từ mã nguồn. Khi một API đã được viết ra theo chuẩn này, nó được gọi là đã được "mô tả". Sau đó, file mô tả này có thể được cả con người và công cụ sử dụng.

2. Swagger là gì?

Swagger là một bộ công cụ phổ biến dùng để thiết kế, xây dựng, quản lý version, và kiểm thử các API. Nó cho phép các nhà phát triển mô tả các API dưới dạng một file YAML hoặc JSON, giúp dễ dàng tạo tài liệu cho API và đảm bảo tính nhất quán trong quá trình phát triển.

Ban đầu, Swagger chỉ bao gồm Swagger UI và một hướng dẫn rất đơn giản về cách viết file YAML để mô tả các API dựa trên HTTP. Sau đó, nhiều công cụ khác bắt đầu được xây dựng dựa trên hướng dẫn này, và dần dần, nó trở thành tiêu chuẩn.

Năm 2015, SmartBear mua lại Swagger và chuyển quyền quản lý phần tiêu chuẩn cho tổ chức Linux Foundation. Trong quá trình này, tiêu chuẩn được đổi tên thành OpenAPI Specification, trong khi SmartBear giữ bản quyền tên Swagger.

Do lịch sử phát triển này, bạn sẽ thấy cả hai thuật ngữ Swagger và OpenAPI được sử dụng lẫn lộn. Tuy nhiên, hiện tại, OpenAPI được khuyến khích sử dụng để chỉ tiêu chuẩn chính, còn Swagger để chỉ các công cụ do SmartBear phát triển (như Swagger UI, Swagger Editor, Swagger Parser, v.v.).

2. Những chức năng chính của Swagger

2.1 Swagger Editor

Swagger Editor là một công cụ trực quan giúp các nhà phát triển viết, kiểm tra, và xem trước các định nghĩa API theo chuẩn OpenAPI. Đây là một ứng dụng mã nguồn mở, có thể sử dụng trực tuyến hoặc tự host trên máy chủ cá nhân. Swagger Editor hỗ trợ cả hai định dạng YAML và JSON để định nghĩa API, giúp dễ dàng tạo tài liệu và kiểm thử API.

2.2 Swagger UI

Swagger UI là một giao diện cho phép trực quan hóa và tương tác với các API đã được mô tả theo chuẩn OpenAPI. Nó hiển thị tài liệu API dưới dạng một trang web, giúp người dùng dễ dàng xem và thử nghiệm các endpoint mà không cần sử dụng thêm công cụ bên ngoài.

2.3 Swagger Codegen

Swagger Codegen là một công cụ tự động sinh ra mã nguồn (code) từ định nghĩa API. Dựa trên định nghĩa API được mô tả bằng OpenAPI, Swagger Codegen có thể sinh ra mã nguồn server hoặc client cho nhiều ngôn ngữ lập trình khác nhau, giúp rút ngắn thời gian phát triển ứng dụng.

Công cụ này hỗ trợ nhiều ngôn ngữ lập trình như Java, Python, PHP, Ruby, ... cho phép các nhà phát triển nhanh chóng tạo ra mã nguồn cơ bản để bắt đầu triển khai API.

2.3 SwaggerHub Explore

SwaggerHub Explore được thiết kế để cung cấp một nền tảng toàn diện cho việc khám phá, kiểm thử và tạo định nghĩa OpenAPI cho các API mà không cần phải sử dụng nhiều công cụ riêng lẻ.

Tất cả các bước từ việc kiểm thử API, xác minh tính hợp lệ, đến tạo tài liệu OpenAPI đều có thể được thực hiện trong cùng một giao diện. Điều này giúp tăng cường hiệu quả và đơn giản hóa quy trình phát triển API.

2.4 SwaggerHub

SwaggerHub Explore là một phần của SwaggerHub. Trong khi SwaggerHub Explore tập trung vào việc kiểm thử và tạo tài liệu OpenAPI thông qua việc gửi các yêu cầu HTTP và phản hồi, thì SwaggerHub có nhiều chức năng hơn, cung cấp môi trường quản lý API toàn diện, bao gồm việc kiểm soát phiên bản API, cộng tác với các thành viên trong nhóm, và lưu trữ các định nghĩa API trong một không gian chung.

Nếu nhóm của bạn bạn đang phát triển API, SwaggerHub sẽ đóng vai trò quản lý toàn bộ vòng đời của API, như:

• Lưu trữ và quản lý định nghĩa OpenAPI: Sau khi bạn tạo ra định nghĩa OpenAPI từ SwaggerHub Explore, bạn có thể lưu trữ nó trên SwaggerHub. Nền tảng này sẽ giúp bạn quản lý các phiên bản của API, theo dõi thay đổi, và đảm bảo tính nhất quán trong quá trình phát triển.
• Cộng tác trong nhóm: SwaggerHub cho phép các thành viên trong nhóm làm việc cùng nhau trên định nghĩa API. Các thành viên có thể xem, chỉnh sửa, và bình luận trên tài liệu API trực tiếp trong nền tảng, giúp quá trình phát triển và tài liệu hóa API trở nên dễ dàng và hiệu quả hơn.
• Tích hợp với các công cụ khác: SwaggerHub có thể tích hợp với các hệ thống CI/CD và các công cụ quản lý mã nguồn như GitHub, GitLab, Jenkins,... Giúp bạn đưa các định nghĩa API từ SwaggerHub Explore vào quy trình phát triển tự động và triển khai chúng một cách nhanh chóng.

Cũng tương tự như Postman, SwaggerHub sẽ có tính phí nếu bạn muốn cộng tác với các thành viên khác trong nhóm (số lượng thành viên > 1 người) để cùng phát triển API.

3. Hướng dẫn sử dụng Swagger cơ bản

3.1 SwaggerHub

• Bước 1: Tạo tài khoản hoặc đăng nhập bằng tài khoản hiện có. SwaggerHub có gói miễn phí với các tính năng cơ bản và gói trả phí cho các tính năng cao cấp hơn.
• Bước 2: chọn Create New -> Chọn API để bắt đầu tạo API mới -> Điền các thông tin cơ bản như: API Name, Version, Spec Format -> Chọn Create API.
• Bước 3: Sau khi tạo API, SwaggerHub sẽ hiển thị Swagger Editor, nơi bạn có thể chỉnh sửa và viết định nghĩa API bằng định dạng OpenAPI. Phần bên trái là nơi bạn chỉnh sửa mã YAML hoặc JSON. Phần bên phải hiển thị tài liệu API trực quan thông qua Swagger UI.
• Bước 4: Nếu bạn muốn kiểm thử một API hiện có, bạn có thể dùng SwaggerHub Explore. Do phần này dài nên mình để hướng dẫn ở mục tiếp theo bên dưới nha.
• Bước 5: SwaggerHub hỗ trợ tính năng cộng tác nhóm. Bạn có thể chia sẻ định nghĩa API với các thành viên trong nhóm:
  Public API: Chia sẻ API công khai, mọi người có thể truy cập.
  Private API: Giới hạn quyền truy cập API chỉ cho các thành viên trong nhóm. (đây là tính năng bị tính phí đấy các bạn).

3.2 SwaggerHub Explore

Bạn muốn kiểm thử và tạo tài liệu OpenAPI cho các endpoint của một API, cụ thể là endpoint cho phép lấy danh sách tất cả các sản phẩm.

• Bước 1: Trước tiên, bạn truy cập SwaggerHub Explore thông qua trình duyệt. Bạn không cần cài đặt hay cấu hình gì thêm vì công cụ này hoàn toàn online.
• Bước 2: Bạn nhập URL của endpoint API mà bạn muốn kiểm thử, ví dụ: https://api.example.com/products. Chọn phương thức HTTP là GET vì bạn muốn lấy danh sách sản phẩm. Nếu API của bạn yêu cầu Authorization, bạn có thể thêm thông tin này vào header của yêu cầu (SwaggerHub Explore có giao diện hỗ trợ việc này).
• Bước 3: SwaggerHub Explore sẽ gửi yêu cầu tới API và hiển thị kết quả trả về ngay lập tức. Ví dụ, phản hồi có thể là: [{"id": 1,"name": "Laptop","price": 1200},{"id": 2,"name": "Smartphone","price": 800}]
• Bước 4: Sau khi xem phản hồi, bạn có thể tạo định nghĩa OpenAPI từ yêu cầu này ngay trong SwaggerHub Explore. Hệ thống sẽ tự động phân tích và tạo ra cấu trúc OpenAPI, ví dụ 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: Sau khi đã hoàn tất kiểm thử và tài liệu hóa, bạn có thể xuất file OpenAPI dưới dạng YAML hoặc JSON để chia sẻ với team của mình, hoặc tích hợp vào quy trình phát triển API. File này có thể được sử dụng để tự động tạo mã nguồn client/server hoặc để tạo tài liệu API tương tác với Swagger UI.

4. Kết luận

Swagger là một hệ sinh thái được thiết kế để giúp các Developer tạo, kiểm thử và tài liệu hóa API dựa trên tiêu chuẩn OpenAPI. Từ việc tạo ra định nghĩa API bằng Swagger Editor, hiển thị và thử nghiệm thông qua Swagger UI, đến việc tự động sinh mã nguồn client/server bằng Swagger Codegen, Swagger giúp quy trình phát triển API trở nên dễ dàng và hiệu quả hơn.

Các bài viết liên quan:

• Expressjs là gì? Framework phổ biến nhất cho Node.js
• CRUD là gì? Vì sao Developer cần phải thành thạo CRUD?
• GraphQL là gì? So sánh GraphQL API và REST API
• API là gì? Những loại API phổ biến và đặc điểm nổi bật