Tìm hiểu Swagger: Công cụ tạo tài liệu API mạnh mẽ cho lập trình viên

Trong thế giới phát triển ứng dụng và hệ thống hiện đại, API đóng vai trò then chốt. API (Application Programming Interface – Giao diện lập trình ứng dụng) là tập hợp các phương thức và giao thức cho phép các ứng dụng và thư viện khác nhau kết nối và tương tác với nhau. API cho phép truy xuất đến các hàm và trao đổi dữ liệu giữa các ứng dụng.

Do đó, tài liệu hướng dẫn API là vô cùng cần thiết. Đây là tài liệu kỹ thuật chứa mọi thông tin cần thiết để làm việc với API, bao gồm chi tiết về tài nguyên, phương thức, request và response, thông tin xác thực, hướng dẫn và ví dụ. Swagger là một công cụ phổ biến giúp tạo tài liệu hướng dẫn API hiệu quả.

Mục Lục

1 Swagger là gì?
2 Cấu trúc cơ bản của file Swagger
3 API Host và Base URL
4 Paths và Operations
5 Parameters
6 Response API

Swagger là gì?

Swagger là một bộ công cụ mã nguồn mở, hỗ trợ xây dựng OpenAPI specifications. OpenAPI giúp thiết kế, xây dựng tài liệu và sử dụng REST APIs. Swagger cung cấp ba công cụ chính cho các nhà phát triển:

Swagger-Editor: Thiết kế API mới hoặc chỉnh sửa API hiện có thông qua tệp cấu hình.
Swagger-Codegen: Tạo mã nguồn từ các tệp cấu hình có sẵn.
Swagger-UI: Tạo giao diện tài liệu từ tệp cấu hình theo chuẩn OpenAPI, cho giao diện rõ ràng, dễ đọc cho cả lập trình viên và người dùng.

Trong số các công cụ trên, Swagger UI được sử dụng rộng rãi nhất. Nó tạo ra giao diện tài liệu từ file config theo chuẩn OpenAPI. Giao diện được hiển thị rõ ràng và tường minh, giúp lập trình viên và người dùng dễ dàng đọc và hiểu. Nó sử dụng file config nhưng hoàn toàn tách biệt các tác vụ với nhau. Bài viết này sẽ giới thiệu Swagger phiên bản 2.0.

Giao diện Swagger UI trực quan giúp dễ dàng tương tác và thử nghiệm API

Cấu trúc cơ bản của file Swagger

File Swagger có thể được viết bằng định dạng JSON hoặc YAML. Dưới đây là cấu trúc cơ bản:

Metadata (Siêu dữ liệu): Mọi thông số kỹ thuật của Swagger bắt đầu bằng phiên bản Swagger. Phiên bản Swagger xác định cấu trúc tổng thể của đặc tả API, bao gồm những gì bạn có thể ghi lại và cách ghi lại nó. Ngoài ra, các thông tin chi tiết như tiêu đề, mô tả và phiên bản của API hiện tại cũng được khai báo tại đây.
Base URL (URL cơ sở): Xác định host của server, đường dẫn cơ bản và giao thức (HTTPS hoặc HTTP).
Consumes, Produces: Xác định các loại MIME mà API hỗ trợ.
Paths (Đường dẫn): Xác định các điểm cuối (endpoint) riêng lẻ trong API và các phương thức HTTP (hoạt động) được hỗ trợ bởi các điểm cuối này. Đây là phần quan trọng chứa thông tin về API, bao gồm đường dẫn API, phương thức (GET, POST, PUT…), request (query, path, body…) và response API.

API Host và Base URL

REST APIs có một URL cơ sở mà các đường dẫn điểm cuối được nối vào. URL này được định nghĩa bởi schema, host và basePath.

host: sentayho.com.vn
basePath: /v2
schemes:
  - https

Tất cả API đều dựa trên URL này. Ví dụ:

Schema: Giao thức truyền được API sử dụng. Swagger hỗ trợ hai giao thức: HTTP và HTTPS.

schemes:
  - http
  - https

Host: Tên miền hoặc địa chỉ IP (IPv4) của máy chủ cung cấp API. Nó có thể bao gồm số cổng nếu khác với cổng mặc định của lược đồ (80 cho HTTP và 443 cho HTTPS). Lưu ý rằng đây chỉ phải là máy chủ lưu trữ, không có http(s):// hoặc đường dẫn phụ.

sentayho.com.vn
sentayho.com.vn:8089
93.184.216.34
93.184.216.34:8089

basePath: Tiền tố URL cho tất cả các đường dẫn API, liên quan đến gốc máy chủ. Nó phải bắt đầu bằng dấu gạch chéo (/). Nếu basePath không được chỉ định, nó sẽ mặc định là /, nghĩa là tất cả các đường dẫn đều bắt đầu từ máy chủ gốc.

/v2
/api/v2
/

Paths và Operations

Paths là các điểm cuối (tài nguyên) mà API của bạn hiển thị, chẳng hạn như /pet. Operations là các phương thức HTTP được sử dụng để thao tác các đường dẫn này, chẳng hạn như GET, POST hoặc DELETE.

paths:
  /pet:
    post:

Khi đã khai báo đường dẫn đến API và phương thức của API, bạn cần khai báo request input của API, được gọi là Parameters.

Parameters

Trong Swagger, các tham số hoạt động API được xác định trong phần parameters trong định nghĩa hoạt động. Mỗi tham số có tên, kiểu giá trị (đối với tham số giá trị nguyên thủy) hoặc lược đồ (đối với nội dung yêu cầu) và mô tả tùy chọn. Các dạng Parameters bao gồm:

Query parameters: Ví dụ: /users?role=admin. Tham số truy vấn là loại tham số phổ biến nhất. Chúng xuất hiện ở cuối URL yêu cầu sau dấu chấm hỏi (?), với các cặp tên=giá trị khác nhau được phân tách bằng dấu và (&). Tham số truy vấn có thể là bắt buộc hoặc tùy chọn.

parameters:
  - in: query
    name: offset
    type: integer
    description: The number of items to skip before starting to collect the result set.
  - in: query
    name: limit
    type: integer
    description: The numbers of items to return.

Path parameters: Ví dụ: /users/{id}. Tham số đường dẫn là các thành phần của đường dẫn URL có thể khác nhau. Chúng thường được sử dụng để trỏ đến một tài nguyên cụ thể trong một bộ sưu tập, chẳng hạn như người dùng được xác định bằng ID. Một URL có thể có một số tham số đường dẫn, mỗi tham số được biểu thị bằng dấu ngoặc nhọn {}.

paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id # Note the name is the same as in the path
          required: true
          type: integer
          minimum: 1
          description: The user ID.
      responses:
        200:
          description: OK

Header parameters: Ví dụ: X-MyHeader: Value. Một lệnh gọi API có thể yêu cầu gửi các tiêu đề tùy chỉnh cùng với một yêu cầu HTTP. Swagger cho phép bạn xác định tiêu đề yêu cầu tùy chỉnh như trong tham số tiêu đề. Ví dụ: giả sử một cuộc gọi tới GET /ping yêu cầu tiêu đề X-Request-ID:

paths:
  /ping:
    get:
      summary: Checks if the server is alive.
      parameters:
        - in: header
          name: X-Request-ID
          type: string
          required: true

Body parameters: Sử dụng trong phần body của các request POST, PUT và PATCH. Các yêu cầu POST, PUT và PATCH có thể có phần thân yêu cầu (tải trọng), chẳng hạn như dữ liệu JSON hoặc XML. Theo thuật ngữ Swagger, nội dung yêu cầu được gọi là tham số nội dung. Chỉ có thể có một tham số nội dung, mặc dù hoạt động có thể có các tham số khác (đường dẫn, truy vấn, tiêu đề).

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            type: object
            required:
              - userName
            properties:
              userName:
                type: string
              firstName:
                type: string
              lastName:
                type: string

Form parameters: Sử dụng cho các request truyền lên nhiều data, ví dụ như việc upload file.

paths:
  /survey:
    post:
      summary: A sample survey.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: name
          type: string
          description: A person’s name.
        - in: formData
          name: fav_number
          type: number
          description: A person’s favorite number.

Response API

Một API cần chỉ định các phản hồi cho tất cả các hoạt động API. Mỗi thao tác phải có ít nhất một phản hồi được xác định, thường là một phản hồi thành công. Phản hồi được xác định bằng mã trạng thái HTTP của nó và dữ liệu được trả về trong nội dung phản hồi và/hoặc tiêu đề.

paths:
  /ping:
    get:
      produces:
        - application/json
      responses:
        200:
          description: OK

Trong câu trả lời, mỗi định nghĩa phản hồi bắt đầu bằng một mã trạng thái, chẳng hạn như 200 hoặc 404. Một hoạt động thường trả về một mã trạng thái thành công và một hoặc nhiều trạng thái lỗi. Mỗi trạng thái phản hồi yêu cầu một mô tả.

responses:
  200:
    description: OK
  400:
    description: Bad request. User ID must be an integer and bigger than 0.
  401:
    description: Authorization information is missing or invalid.
  404:
    description: A user with the specified ID was not found.

Ngoài những trạng thái status, chúng ta có thể khai báo những dạng dữ liệu mà API sẽ trả về.

responses:
  200:
    description: A User object
    schema:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.

Một tính năng rất hữu ích của Swagger là hỗ trợ $ref. Nó giúp chúng ta có thể sử dụng lại những data mà ta đã định nghĩa, tránh việc trùng lặp hay khai báo nhiều lần.

responses:
  200:
    description: A Pet object
    schema:
      $ref: '#/definitions/Pet'
  "405":
    description: "Invalid input"
definitions:
  Pet:
    type: "object"
    properties:
      id:
        type: "integer"
      name:
        type: "string"
        example: "doggie"
      status:
        type: "string"
        description: "pet status in the store"

Như vậy, chúng ta đã tìm hiểu cơ bản để viết được một file swagger định nghĩa API. Dưới đây là một ví dụ:

swagger: "2.0"
info:
  description: "demo"
  version: "1.0.0"
  title: "Swagger Petstore"
host: "petstore.swagger.io"
basePath: "/v2"
schemes:
  - "https"
  - "http"
paths:
  /pet:
    post:
      tags:
        - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
        - "application/json"
        - "application/xml"
      produces:
        - "application/xml"
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Pet object that needs to be added to the store"
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        "200":
          description: "Success"
        "405":
          description: "Invalid input"
  /pets/{id}:
    get:
      tags:
        - "pet"
      summary: "Get Pet of Store"
      description: "Get Pet of Store"
      operationId: "getPets"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: integer
          required: true
          description: Numeric ID of the user to get.
      responses:
        200:
          description: A Pet object
          schema:
            $ref: '#/definitions/Pet'
        "405":
          description: "Invalid input"
definitions:
  Pet:
    type: "object"
    properties:
      id:
        type: "integer"
      name:
        type: "string"
        example: "doggie"
      status:
        type: "string"
        description: "pet status in the store"

Hy vọng bài viết này sẽ giúp bạn hiểu và sử dụng Swagger một cách hiệu quả.