Site icon saotuvi.com

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

Ms Gao

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.

Yaml

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.).

💡

OpenAPI là tiêu chuẩn dùng để mô tả (describe) API, còn Swagger là tên của các công cụ hỗ trợ việc làm việc với API do SmartBear phát triển.

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

💡

Khi có ngân sách: Bạn nên dùng SwaggerHub cho toàn bộ quy trình quản lý API, từ phát triển đến cộng tác, phiên bản hóa và tích hợp. SwaggerHub sẽ giúp tiết kiệm thời gian và cung cấp môi trường quản lý chuyên nghiệp, đặc biệt là cho các doanh nghiệp lớn hoặc đội ngũ phát triển nhiều người.

Khi không có ngân sách: Bạn có thể tự host các công cụ như Swagger UI, Swagger Editor, và Swagger Codegen, tất cả đều miễn phí và mã nguồn mở. Phù hợp cho các nhóm phát triển nhỏ hoặc cá nhân muốn tiết kiệm chi phí mà vẫn có thể phát triển và tạo version API một cách chuyên nghiệp.

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ư:

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

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.

Yaml

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

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:

Exit mobile version