Posted inDevelopment

Swagger (OpenAPI 3.0): Tuyệt chiêu ‘dẹp loạn’ tài liệu API cho Developer

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Nỗi ám ảnh mang tên “Tài liệu API”

Bạn đã bao giờ code xong 10 cái endpoint, hí hửng bàn giao rồi bị bên Frontend “réo” tên liên tục chưa? Những câu hỏi như: “Endpoint này nhận tham số gì?”, “Header cần truyền gì?” hay “Dữ liệu trả về trông ra sao?” có thể đốt sạch cả buổi chiều của bạn. Trước đây, mình thường viết docs bằng file Excel. Tuy nhiên, chỉ cần sửa một dòng code là tài liệu trở nên lỗi thời ngay lập tức.

Trong một dự án web app với 5 developer, mình thử áp dụng Swagger (OpenAPI 3.0). Kết quả thật bất ngờ. Team mình tiết kiệm được khoảng 30% thời gian họp hành chỉ để giải thích code. Thay vì ngồi chat qua lại, mình chỉ cần gửi duy nhất một đường link Swagger UI. Mọi người có thể test API trực tiếp trên trình duyệt mà không cần mở Postman hay Insomnia.

OpenAPI 3.0 và Swagger: Đừng nhầm lẫn!

Nhiều bạn mới thường dùng hai tên gọi này thay thế cho nhau. Thực tế, chúng có vai trò khác biệt:

  • OpenAPI Specification (OAS): Đây là bộ quy chuẩn (standard). Nó giống như bản thiết kế blueprint giúp cả người và máy đều hiểu cấu trúc API mà không cần đọc code.
  • Swagger: Đây là hệ sinh thái công cụ để thực thi chuẩn OpenAPI đó. Swagger UI dùng để hiển thị giao diện, còn Swagger Editor giúp bạn soạn thảo spec nhanh hơn.

Phiên bản 3.0 là một bước tiến lớn so với 2.0. Nó cấu trúc lại phần components cực kỳ khoa học, hỗ trợ nhiều server URL và mô tả các kiểu dữ liệu phức tạp chuẩn xác hơn nhiều.

Thực hành: Tích hợp Swagger vào Node.js trong 5 phút

Để dễ hình dung, mình sẽ hướng dẫn bạn tích hợp Swagger vào dự án Express. Chúng ta sẽ dùng swagger-jsdoc để đọc annotation và swagger-ui-express để tạo giao diện tương tác.

Bước 1: Khởi tạo dự án

Hãy mở terminal và gõ các lệnh sau để cài đặt môi trường:

mkdir swagger-demo
cd swagger-demo
npm init -y
npm install express swagger-jsdoc swagger-ui-express

Bước 2: Cấu hình Swagger Definition

Tạo file server.js. Đây là nơi bạn khai báo các thông tin “mặt tiền” của API như phiên bản, tiêu đề và môi trường chạy.

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();
const port = 3000;

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User Management API',
      version: '1.0.0',
      description: 'Ví dụ quản lý User đơn giản',
    },
    servers: [{ url: 'http://localhost:3000' }],
  },
  apis: ['./server.js'], 
};

const swaggerDocs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(port, () => {
  console.log(`Docs tại: http://localhost:${port}/api-docs`);
});

Bước 3: Viết Annotation ngay trong code

Đây là phần mình thích nhất. Thay vì viết tài liệu ở một file xa xôi, bạn viết ngay trên đầu hàm xử lý route. Khi bảo trì code, bạn sẽ thấy ngay tài liệu tương ứng, cực kỳ khó quên cập nhật.

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Lấy danh sách người dùng
 *     responses:
 *       200:
 *         description: Trả về mảng user thành công
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id: { type: integer }
 *                   name: { type: string }
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'Nguyen Van A' }]);
});

Kinh nghiệm “xương máu” khi làm dự án lớn

Khi API lên đến con số hàng chục, việc nhét tất cả vào một file sẽ là thảm họa. Dưới đây là 3 lưu ý giúp bạn quản lý Swagger chuyên nghiệp hơn:

  1. Chia để trị: Hãy tách annotation ra các file route riêng biệt như auth.routes.js hay product.routes.js. Sau đó dùng regex apis: ['./routes/*.js'] để quét toàn bộ.
  2. Tận dụng Components: Đừng lặp lại cấu trúc object ở mọi nơi. Hãy định nghĩa một Schema chung trong phần components và dùng $ref để trỏ đến.
  3. Cấu hình Bảo mật: Nếu API dùng JWT, hãy thêm securitySchemes. Swagger UI sẽ hiện nút “Authorize”, cho phép bạn dán token vào để test mọi endpoint bị khóa.
// Định nghĩa Security Scheme để test JWT
components: {
  securitySchemes: {
    bearerAuth: {
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'JWT',
    }
  }
}

Tóm lại là

Đầu tư làm Swagger không hề lãng phí thời gian. Nó giúp team hiểu nhau hơn và chứng tỏ bạn là một developer có quy trình làm việc chuyên nghiệp. Nếu bạn đang làm Backend, hãy áp dụng OpenAPI 3.0 ngay hôm nay. Tin mình đi, gánh nặng giải thích code của bạn sẽ được trút bỏ đáng kể.

Share:
Tags: