OpenAPI / Swagger

1. OpenAPI và Swagger là gì?

Khi xây dựng backend bằng Go và Gin, developer thường định nghĩa các endpoint như GET /users, POST /users hoặc GET /users/{id}. Tuy nhiên, việc có endpoint hoạt động không đồng nghĩa với việc người khác biết cách sử dụng chúng.

OpenAPI là gì?

OpenAPI Specification (OAS) là một đặc tả độc lập với ngôn ngữ lập trình, dùng để mô tả HTTP API. Đặc tả này có thể viết bằng YAML hoặc JSON và bao gồm những thông tin như endpoint, HTTP method, parameters, request body, response, authentication và schema dữ liệu.

Ví dụ, thay vì chỉ nhìn thấy route:

POST /api/v1/users

OpenAPI có thể mô tả rõ endpoint này cần request body gồm name và email, trả về 201 Created khi tạo thành công, 400 Bad Request khi dữ liệu không hợp lệ và 409 Conflict khi email bị trùng.

OpenAPI giúp biến những quy ước thường chỉ được hiểu ngầm trong code thành một bản mô tả có cấu trúc, có thể được đọc bởi developer lẫn các công cụ phần mềm.

Swagger là gì?

Swagger là hệ sinh thái công cụ làm việc với OpenAPI, không phải một framework backend như Gin. Một số công cụ phổ biến gồm Swagger UI để hiển thị tài liệu tương tác, Swagger Editor để viết và kiểm tra đặc tả, cùng các công cụ sinh client hoặc server code từ đặc tả.

Có thể phân biệt ba khái niệm:

• OpenAPI: Chuẩn mô tả HTTP API.
• Swagger UI: Công cụ hiển thị tài liệu API và cho phép thử request trên giao diện web.
• Swagger Editor: Công cụ viết, chỉnh sửa và kiểm tra file OpenAPI.

2. OpenAPI khác Gin-Gonic như thế nào?

Gin xử lý HTTP request thực tế. Nó đăng ký route, gọi handler, đọc dữ liệu client gửi lên, chạy middleware và trả response. OpenAPI không thực hiện những công việc đó; nó mô tả API cần có những endpoint nào, request và response có cấu trúc ra sao.

Ví dụ, Gin có thể khai báo:

router.POST("/api/v1/users", createUser)

Đoạn code này đăng ký endpoint cho application. Nhưng chỉ nhìn vào đó, người sử dụng API chưa thể biết chính xác request body cần những trường nào, trường nào bắt buộc hoặc response có dạng gì.

OpenAPI bổ sung bản mô tả:

paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
        '400':
          description: Invalid request

Đặc tả này giúp công cụ hiểu rằng API có thao tác tạo user, nhận JSON body và có các kết quả được mô tả.

3. Parameters – Mô tả dữ liệu đầu vào

HTTP API có thể nhận tham số từ path, query string, headers hoặc cookies. OpenAPI cho phép mô tả vị trí, tên, kiểu dữ liệu và những ràng buộc của từng parameter.

Path Parameter

Path parameter là một phần của đường dẫn, thường dùng để xác định một resource cụ thể.

Ví dụ:

GET /users/10

Trong OpenAPI, endpoint có thể được khai báo như sau:

/users/{id}:
  get:
    summary: Get user by ID
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    responses:
      '200':
        description: User found
      '404':
        description: User not found

Dấu {id} trong path là biến cần được cung cấp khi gọi API. Vì nó nằm trong đường dẫn, parameter có in: path và phải có required: true.

Query Parameter

Query parameter thường dùng để lọc, tìm kiếm, sắp xếp hoặc phân trang danh sách.

Ví dụ:

GET /users?page=2&limit=10

OpenAPI có thể mô tả:

parameters:
  - name: page
    in: query
    required: false
    schema:
      type: integer
      minimum: 1
      default: 1

  - name: limit
    in: query
    required: false
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 10

Những thông tin như minimum, maximum và default giúp người đọc hiểu cách truyền dữ liệu. Các công cụ có thể dùng thông tin schema để hiển thị input phù hợp hoặc kiểm tra một số điều kiện của dữ liệu.

4. Request Body và Schema

Đối với các thao tác như tạo hoặc cập nhật dữ liệu, API thường nhận JSON body. OpenAPI sử dụng requestBody để mô tả dữ liệu này và schema để xác định cấu trúc.

Ví dụ request tạo user:

{
  "name": "John",
  "email": "[email protected]"
}

Có thể khai báo schema:

components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email

type: object cho biết dữ liệu có cấu trúc object. Trường required xác định các thuộc tính bắt buộc; properties mô tả từng thuộc tính và kiểu dữ liệu tương ứng.

Phần request body tham chiếu schema này:

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateUserRequest'

$ref giúp tái sử dụng định nghĩa đã khai báo ở nơi khác. Nếu nhiều endpoint cùng nhận cấu trúc dữ liệu tương tự, có thể dùng chung một schema để tránh lặp nội dung và giảm nguy cơ tài liệu không nhất quán.

5. Swagger UI – Hiển thị và thử nghiệm API

Sau khi có file OpenAPI, có thể sử dụng Swagger UI để hiển thị tài liệu ở dạng giao diện web tương tác. Thay vì phải đọc toàn bộ YAML, developer có thể xem danh sách endpoint, mở từng operation, xem parameters, request body, response schema và thử gửi request ngay trên giao diện.

Ví dụ, giao diện có thể hiển thị GET /users/{id} cùng input cho id, sau đó cho phép gửi request và quan sát status code cùng response body thực tế.

Swagger UI hữu ích trong quá trình phát triển vì frontend developer có thể tự kiểm tra cách API hoạt động thay vì phải liên tục hỏi backend về request format. Nó cũng hữu ích trong giai đoạn kiểm thử tích hợp vì một số request có thể được thực hiện trực tiếp từ trình duyệt.

6. Tổng kết

OpenAPI và Swagger là những công cụ quan trọng trong quy trình xây dựng và tích hợp API.

OpenAPI cung cấp định dạng chuẩn để mô tả endpoint, parameters, request body, response, schema và authentication. Swagger UI giúp trình bày đặc tả thành tài liệu tương tác; Swagger Editor hỗ trợ viết và kiểm tra đặc tả; các công cụ sinh code có thể dùng hợp đồng đó để tạo client hoặc server scaffolding.

Thuận Đức

Xem tất cả bài viết của tác giả

Bài viết khác

PHP & Laravel Fundamentals

PHP là gì? — Ngôn ngữ lập trình phía máy chủ và vai trò trong phát triển web PHP là gì?   PHP (viết tắt của PHP: Hypertext Preprocessor) là một ngôn ngữ lập trình phía máy chủ, thường được sử dụng để xây dựng website và ứng dụng web động. Trong mô hình phát […]

Đọc thêm

Gin-Gonic Fundamentals

1. Gin-Gonic là gì? Gin, thường được gọi là Gin-Gonic, là một HTTP web framework viết bằng Go. Framework này cung cấp các công cụ để xây dựng web server và REST API mà không cần tự triển khai toàn bộ việc định tuyến request, đọc dữ liệu HTTP, tạo response hay quản lý middleware. […]

Đọc thêm

Test Case & Test Plan & Test Data

1. Lời mở đầu và vị trí nền tảng của bộ ba quản lý kiểm thử trong dự án phần mềm Trong quy trình sản xuất phần mềm hiện đại, nếu hoạt động lập trình (Coding) là việc hiện thực hóa các ý tưởng thiết kế thành sản phẩm chạy được, thì hoạt động kiểm […]

Đọc thêm

JWT & Token Authentication

Token Authentication, JWT, Access Token và Refresh Token 1. Token Authentication là gì?   Token Authentication là cơ chế xác thực sử dụng token để chứng minh danh tính hoặc thông tin xác thực của người dùng hay client khi truy cập các tài nguyên được bảo vệ. Sau khi người dùng đăng nhập thành […]

Đọc thêm

Series 3 – JavaScript Fundamentals : JavaScript → DOM

Series 3 — JavaScript Fundamentals   JavaScript → DOM → Async → API   Bài 1. JavaScript & DOM – Từ ngôn ngữ lập trình đến tương tác với giao diện Web   1. JavaScript là gì? Trong quá trình xây dựng website, HTML được sử dụng để tạo cấu trúc nội dung, CSS đảm nhiệm việc […]

Đọc thêm

Authentication & Authorization

Authentication & Authorization là gì? Authentication (xác thực) và Authorization (phân quyền) là hai khái niệm quan trọng trong bảo mật hệ thống và API. Nói một cách đơn giản: Authentication: Xác minh bạn là ai. Authorization: Xác định bạn được phép làm gì. Ví dụ, khi đăng nhập vào một hệ thống quản lý […]

Đọc thêm