DPTCloud
Quay lại danh sách
Tin tức công nghệ

Tự host Scalar trên Cloud Server: Giải pháp thay thế Swagger UI tạo trang tài liệu API tương tác thời gian thực tuyệt đẹp

4 tháng 6, 2026

Giới thiệu: Kỷ nguyên mới của tài liệu API

Trong quy trình phát triển phần mềm hiện đại, tài liệu API (API Documentation) không chỉ đơn thuần là các tệp hướng dẫn khô khan. Nó là cầu nối sống còn giữa các lập trình viên backend, frontend, đối tác và khách hàng. Trong nhiều năm qua, Swagger UI đã trở thành tiêu chuẩn công nghiệp được sử dụng rộng rãi nhất. Tuy nhiên, khi trải nghiệm người dùng (UX) ngày càng được coi trọng, Swagger UI bắt đầu bộc lộ những hạn chế lớn: giao diện lỗi thời, khả năng tùy biến kém, tải chậm với các file OpenAPI lớn và thiếu tính tương tác thời gian thực.

Đó là lý do tại sao Scalar xuất hiện như một vị cứu tinh. Scalar là một nền tảng tài liệu API thế hệ mới, mã nguồn mở, được thiết kế để thay thế Swagger UI. Với giao diện tối giản, hiện đại và tích hợp sẵn một API Client mạnh mẽ, Scalar mang lại trải nghiệm xem và thử nghiệm API mượt mà chưa từng có. Bài viết này sẽ hướng dẫn bạn cách tự host (self-host) Scalar trên Cloud Server của riêng mình để làm chủ hoàn toàn hệ thống tài liệu API của doanh nghiệp.

Tại sao doanh nghiệp nên chuyển từ Swagger UI sang Scalar?

Trước khi đi vào chi tiết kỹ thuật, hãy cùng điểm qua những lý do khiến Scalar nhanh chóng trở thành xu hướng lựa chọn của các tech lead và doanh nghiệp:

  • Giao diện hiện đại và tối giản: Bố cục 3 cột thông minh (Navigation - Content - API Client) giúp lập trình viên dễ dàng theo dõi cấu trúc API, đọc mô tả và thử nghiệm code cùng một lúc mà không cần chuyển đổi qua lại.
  • Tích hợp API Client mạnh mẽ (Thế chỗ Postman): Khác với tính năng "Try it out" cơ bản của Swagger, API Client của Scalar cực kỳ mạnh mẽ, hỗ trợ lưu lịch sử request, tự động tạo code snippet bằng nhiều ngôn ngữ (JavaScript, Python, Go, cURL...) và xử lý authentication (OAuth2, Bearer Token, API Key) rất mượt mà.
  • Hiệu suất vượt trội: Được xây dựng trên các công nghệ hiện đại, Scalar xử lý các file OpenAPI (Swagger 2.0 hoặc OpenAPI 3.0/3.1) dung lượng lớn một cách nhanh chóng, không gặp hiện tượng giật lag như Swagger UI.
  • Khả năng tùy biến sâu: Bạn có thể dễ dàng thay đổi theme, font chữ, thêm logo thương hiệu và cấu hình bảo mật theo tiêu chuẩn riêng của doanh nghiệp.
  • Hỗ trợ Markdown hoàn hảo: Giúp việc viết mô tả, tài liệu hướng dẫn tích hợp (Guides) trở nên trực quan và đẹp mắt hơn.

Chuẩn bị môi trường trước khi cài đặt Scalar

Để tự host Scalar trên Cloud Server, bạn cần chuẩn bị một số thành phần cơ bản sau:

  1. Cloud Server (VPS): Hệ điều hành Ubuntu Server (khuyến nghị phiên bản 22.04 LTS hoặc 24.04 LTS). Cấu hình tối thiểu 1 vCPU và 1GB RAM là đủ cho nhu cầu cơ bản.
  2. Docker và Docker Compose: Công cụ giúp đóng gói và triển khai Scalar một cách nhanh chóng, cô lập môi trường và dễ dàng quản lý.
  3. Tên miền (Domain) và SSL: Một tên miền phụ (ví dụ: api-docs.yourcompany.com) trỏ về IP của Cloud Server để người dùng truy cập an toàn qua HTTPS.
  4. Nginx hoặc Caddy Server: Làm Reverse Proxy để điều hướng traffic từ môi trường ngoài vào container của Scalar và cấu hình SSL (Let's Encrypt).

Hướng dẫn chi tiết các bước tự host Scalar bằng Docker

Lưu ý: Bạn cần truy cập vào Cloud Server của mình thông qua SSH với quyền root hoặc sử dụng lệnh sudo để thực hiện các bước dưới đây.

Bước 1: Cập nhật hệ thống và cài đặt Docker

Đầu tiên, hãy đảm bảo hệ thống của bạn được cập nhật các bản vá bảo mật mới nhất và tiến hành cài đặt Docker Compose:

sudo apt update && sudo apt upgrade -y
sudo apt install docker-compose-plugin docker.io -y

Bước 2: Tạo cấu hình Docker Compose cho Scalar

Scalar cung cấp các image Docker chính thức trên Docker Hub, giúp việc triển khai vô cùng đơn giản. Hãy tạo một thư mục riêng cho dự án và tạo file cấu hình:

mkdir -p ~/scalar-docs && cd ~/scalar-docs
nano docker-compose.yml

Sao chép và dán đoạn mã cấu hình dưới đây vào file docker-compose.yml:

version: '3.8'

services:
  scalar:
    image: @scalar/api-reference:latest
    container_name: scalar_docs
    ports:
      - "5000:5000"
    environment:
      - SCALAR_OPENAPI_URL=[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json)
      - SCALAR_THEME=purple
      - SCALAR_SHOW_SIDEBAR=true
    restart: always

Trong đó, biến môi trường SCALAR_OPENAPI_URL chính là đường dẫn đến file JSON/YAML chứa đặc tả OpenAPI của hệ thống API của bạn. Bạn có thể thay đổi link này thành URL API nội bộ của doanh nghiệp.

Bước 3: Khởi chạy container Scalar

Chạy lệnh sau để Docker tự động tải image và khởi chạy ứng dụng chạy ngầm:

sudo docker compose up -d

Bạn có thể kiểm tra trạng thái hoạt động bằng lệnh sudo docker ps. Lúc này, Scalar đã hoạt động nội bộ tại cổng 5000 của server.

Bước 4: Cấu hình Reverse Proxy với Nginx và cài đặt SSL

Để tài liệu API có thể truy cập được từ bên ngoài Internet qua giao thức HTTPS bảo mật, chúng ta sẽ sử dụng Nginx làm Reverse Proxy. Cài đặt Nginx:

sudo apt install nginx -y

Tạo file cấu hình cho tên miền của bạn:

sudo nano /etc/nginx/sites-available/api-docs.yourcompany.com

Thêm cấu hình điều hướng lưu lượng truy cập vào cổng 5000 của Scalar:

server {
    listen 80;
    server_name api-docs.yourcompany.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kích hoạt cấu hình và khởi động lại Nginx:

sudo ln -s /etc/nginx/sites-available/api-docs.yourcompany.com /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Cuối cùng, hãy sử dụng Certbot để cài đặt chứng chỉ SSL Let's Encrypt miễn phí:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d api-docs.yourcompany.com

Sau khi hoàn tất, Certbot sẽ tự động cấu hình lại Nginx để chuyển hướng toàn bộ traffic từ HTTP sang HTTPS.

Trải nghiệm giao diện và tương tác thời gian thực trên Scalar

Bây giờ, hãy mở trình duyệt và truy cập vào địa chỉ [https://api-docs.yourcompany.com](https://api-docs.yourcompany.com). Bạn sẽ bị ấn tượng ngay lập tức bởi tốc độ tải trang cực nhanh và giao diện sang trọng của Scalar.

Tại thanh điều hướng bên trái, các nhóm API (Tags) và các Endpoint được sắp xếp mạch lạc với các nhãn màu sắc phân biệt rõ ràng các phương thức HTTP (GET, POST, PUT, DELETE). Khi click vào một endpoint, phần nội dung giữa sẽ hiển thị chi tiết các tham số truyền vào (Query parameters, Request Body, Headers) và cấu trúc dữ liệu trả về (Response schema).

Điểm đắt giá nhất chính là cột bên phải — Interactive API Client. Lập trình viên có thể nhập giá trị thực tế, chọn môi trường (Production/Staging), điền mã token xác thực và nhấn nút "Send Request". Kết quả phản hồi từ API bao gồm HTTP Status, thời gian phản hồi (Latency) và dữ liệu JSON sẽ được hiển thị ngay lập tức theo thời gian thực với định dạng màu sắc (syntax highlighting) vô cùng trực quan.

Lời kết và định hướng tối ưu cho doanh nghiệp

Việc chuyển đổi từ Swagger UI sang Scalar và tự host trên Cloud Server là một bước đi chiến lược giúp doanh nghiệp nâng cao trải nghiệm của đội ngũ lập trình, tăng tốc độ phát triển sản phẩm và thể hiện sự chuyên nghiệp đối với các đối tác tích hợp hệ thống. Với khả năng tự làm chủ mã nguồn, dữ liệu tài liệu API của bạn hoàn toàn nằm trong tầm kiểm soát, đảm bảo tính an toàn và bảo mật thông tin nội bộ.

Để tối ưu hóa hơn nữa, bạn có thể tích hợp việc cập nhật file OpenAPI vào quy trình CI/CD (Jenkins, GitHub Actions, GitLab CI). Mỗi khi code backend được cập nhật và sinh ra file spec mới, CI/CD sẽ tự động đẩy file này lên Cloud Server hoặc cập nhật biến môi trường của Docker, giúp trang tài liệu API Scalar luôn luôn được làm mới theo thời gian thực mà không cần can thiệp thủ công.

Tự host Scalar trên Cloud Server: Giải pháp thay thế Swagger UI tạo trang tài liệu API tương tác thời gian thực tuyệt đẹp | DPTCloud