Posted inDevelopment

Tạm biệt Swagger UI ‘cổ đại’: Hướng dẫn tích hợp Scalar vào dự án Node.js

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

Nỗi ám ảnh khi dùng Swagger UI cho các dự án thực tế

Sau 6 tháng triển khai hệ thống quản lý giao dịch cho đối tác Nhật, mình nhận ra một vấn đề chí mạng: Tài liệu API. Dù backend đã viết code chỉn chu và dùng swagger-jsdoc để tự động hóa, giao diện mặc định của Swagger UI vẫn khiến team Frontend và Tester bên đối tác than phiền liên tục.

Vấn đề không nằm ở dữ liệu mà ở trải nghiệm người dùng (UX). Swagger UI trông như một trang web từ năm 2010. Việc tìm kiếm một endpoint trong danh sách hơn 200 API thực sự là cực hình. Tính năng “Try it out” thường xuyên xử lý lóng ngóng với các Object lồng nhau, còn format JSON trả về thì rất khó đọc nếu dữ liệu quá lớn.

Tại sao Swagger UI không còn là lựa chọn số 1?

Swagger UI từng là tiêu chuẩn ngành suốt một thập kỷ qua. Tuy nhiên, khi yêu cầu về Developer Experience (DX) ngày càng khắt khe, nó bắt đầu bộc lộ những hạn chế khó chấp nhận:

  • Giao diện lỗi thời: Việc tùy chỉnh CSS để đồng bộ với bộ nhận diện thương hiệu của dự án cực kỳ phức tạp. Đôi khi chỉ sửa một chút layout cũng khiến toàn bộ trang bị vỡ.
  • Hiệu năng kém: Với các file OpenAPI (JSON/YAML) dài khoảng 10.000 dòng, trình duyệt thường xuyên bị treo hoặc lag khi cuộn trang.
  • API Client quá nghèo nàn: Nó chỉ đơn thuần là gửi request. Bạn không thể quản lý biến môi trường hay lưu lại các Token theo dạng Collection chuyên nghiệp như cách làm việc trên Postman.

Mình từng refactor một hệ thống 50.000 dòng code. Bài học rút ra là tài liệu API tốt giúp tiết kiệm ít nhất 30% thời gian họp hành chỉ để giải thích logic cho team Frontend.

Các phương án thay thế thường gặp

Trước khi chuyển hẳn sang Scalar, mình đã cân nhắc vài cái tên phổ biến:

  1. Redoc: Giao diện chuyên nghiệp, hỗ trợ menu bên trái rất khoa học. Tuy nhiên, bản miễn phí không cho phép test API trực tiếp trên trình duyệt.
  2. Stoplight Elements: Hiện đại nhưng cấu hình khá nặng nề cho các dự án Express.js quy mô vừa và nhỏ.
  3. Postman/Insomnia: Đây là công cụ rời. Bạn phải export file rồi gửi thủ công cho đồng nghiệp, dẫn đến tình trạng sai lệch phiên bản giữa code và tài liệu.

Scalar – Làn gió mới cho API Documentation

Scalar là sự kết hợp giữa vẻ đẹp của Redoc và tính tiện dụng của Postman. Thư viện này nhẹ, hỗ trợ sinh Code Snippets cho hơn 15 ngôn ngữ lập trình và tích hợp cực sâu vào hệ sinh thái Node.js.

Bước 1: Cài đặt thư viện

Nếu bạn đang dùng Express.js, hãy cài đặt gói adapter của Scalar cùng với swagger-jsdoc để quét định nghĩa API:

npm install @scalar/express-api-reference swagger-jsdoc

Bước 2: Cấu hình OpenAPI Specification

Trong file app.js, bạn định nghĩa thông tin cơ bản cho API như sau:

const swaggerJsdoc = require('swagger-jsdoc');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Dự án API Node.js',
      version: '1.0.0',
      description: 'Tài liệu API sử dụng Scalar',
    },
    servers: [{ url: 'http://localhost:3000' }],
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(swaggerOptions);

Bước 3: Tích hợp Scalar Middleware

Thay vì dùng swagger-ui-express, bạn chỉ cần thay bằng Scalar với vài dòng code đơn giản:

const express = require('express');
const { apiReference } = require('@scalar/express-api-reference');
const app = express();

app.use(
  '/docs',
  apiReference({
    spec: { content: specs },
  }),
);

app.listen(3000, () => {
  console.log('Tài liệu API tại: http://localhost:3000/docs');
});

Trải nghiệm thực tế sau 6 tháng sử dụng

Điểm đáng tiền nhất của Scalar là Integrated API Client. Khi mở một endpoint, giao diện bên phải sẽ hiển thị một trình giả lập request giống hệt Postman. Bạn có thể chọn ngôn ngữ như Node.js, Python hoặc Go để copy code mẫu dùng ngay lập tức.

Tùy biến theme trong một nốt nhạc

Scalar cho phép đổi theme chỉ với một dòng cấu hình. Nếu bạn thích phong cách GitHub hay Solarized, chỉ cần thêm thuộc tính theme:

apiReference({
  theme: 'purple', // Options: 'default', 'moon', 'purple', 'solarized'
  spec: { content: specs },
})

Tìm kiếm siêu tốc với phím tắt

Phím tắt Ctrl + K là cứu cánh cho các dự án lớn. Nó mở thanh tìm kiếm toàn cục, giúp bạn nhảy thẳng tới endpoint cần tìm mà không cần cuộn chuột mỏi tay.

Vài lưu ý nhỏ từ thực tế

Thú thực, lúc mới chuyển sang Scalar, mình từng gặp lỗi hiển thị với các Object lồng nhau quá sâu. Tuy nhiên, team phát triển xử lý Issue trên GitHub rất nhanh, thường có bản vá ngay trong tuần.

Nếu bạn dùng NestJS, Scalar cũng có sẵn bản integration cực mượt. Đừng quên cấu hình securitySchemes để Scalar hiển thị ô nhập Bearer Token trông chuyên nghiệp nhất.

Tóm lại, nếu đã chán ngấy giao diện cũ kỹ của Swagger UI, Scalar là lựa chọn nâng cấp đáng giá nhất hiện nay. Nó không chỉ làm đẹp tài liệu mà còn thực sự cải thiện tốc độ làm việc cho cả team.

Share:
Tags: