Tạo tài liệu Swagger UI trực tuyến: Giải pháp sử dụng trong môi trường không có kết nối Internet

Trong các mạng nội bộ doanh nghiệp, môi trường bảo mật hoặc nơi có kết nối mạng không ổn định, các nhà phát triển thường gặp khó khăn khi truy cập các công cụ tài liệu API trực tuyến. Swagger UI, là một trong những công cụ phổ biến nhất để hiển thị các đặc tả OpenAPI, cung cấp giải pháp triển khai ngoại tuyến đầy đủ, giúp việc xem và kiểm thử tài liệu API không phụ thuộc vào mạng. Bài viết này sẽ giới thiệu ba cách triển khai ngoại tuyến hữu ích, giúp các nhóm làm việc sử dụng tài liệu API hiệu quả hơn trong môi trường không có kết nối Internet.

Kế hoạch 1: Triển Khai Tệp tĩnh (Đề xuất cho Người Dùng Thường)

Bước Chuẩn Bị

1. Clone dự án về máy tính cá nhân:

   git clone https://gitcode.com/gh_mirrors/swa/swagger-ui

2. Vào thư mục dự án và cài đặt các phụ thuộc:

   cd swagger-ui && npm install

Xây Dựng Tài Nguyên Ngoại Tuyến

Chạy lệnh sau để tạo các tệp tĩnh:

npm run build

Sau khi xây dựng hoàn tất, thư mục gốc dự án sẽ chứa thư mục dist, bao gồm tất cả các tệp HTML, CSS và JavaScript cần thiết. Xem thêm tại Hướng dẫn cài đặt.

Cấu Hình Đặc tả API Nội Bộ

1. Sao chép thư mục dist đến máy chủ đích hoặc thư mục địa phương
2. Chỉnh sửa tệp dist/init-swagger.js, thay đổi URL API mặc định thành đường dẫn tệp cục bộ:

   window.onload = function() {
     const ui = SwaggerUIBundle({
       url: "api-nhanh.json",  // Thay đổi thành đường dẫn tới tệp JSON/YAML cục bộ
       dom_id: '#swagger-ui',
       presets: [
         SwaggerUIBundle.presets.apis,
         SwaggerUIStandalonePreset
       ],
       layout: "StandaloneLayout"
     });
     window.ui = ui;
   };

3. Sao chép tệp đặc tả API của bạn (ví dụ: api-open.json) vào thư mục dist

Cách Sử Dụng

Mở trực tiếp tệp dist/index.html trong trình duyệt để xem tài liệu ngoại tuyến. Không cần máy chủ Web, chỉ cần chạy bằng tệp tĩnh, phù hợp với môi trường hoàn toàn ngoại tuyến.

Kế hoạch 2: Triển Khai Sử Dụng Docker (Đề Xuất cho Quản Lý IT)

Xây Dựng Ảnh Docker Địa Phương

1. Trong thư mục gốc dự án, thực hiện lệnh xây dựng Docker:

   docker build -t swagger-ui-offline .

2. Chạy container và gắn đặc tả API cục bộ:

   docker run -p 8080:8080 \
     -v $(pwd)/api-nhanh.json:/usr/share/nginx/html/api-nhanh.json \
     -e SWAGGER_JSON=/usr/share/nginx/html/api-nhanh.json \
     swagger-ui-offline

Cấu Hình Tham Số Container

Các biến môi trường phổ biến:

Tham số	Mô tả	Ví dụ
SWAGGER_JSON	Đường dẫn tới tệp đặc tả API cục bộ	-e SWAGGER_JSON=/app/api.json
BASE_URL	Đặt đường dẫn truy cập cơ sở	-e BASE_URL=/swagger
DEEP_LINKING	Kích hoạt chức năng liên kết sâu	-e DEEP_LINKING=true

Xem cấu hình đầy đủ tại Tài liệu cấu hình.

Truy Cập Tài Liệu Ngoại Tuyến

Truy cập http://localhost:8080 trong trình duyệt để sử dụng. Lợi ích của giải pháp Docker bao gồm tính nhất quán môi trường và dễ triển khai, phù hợp cho việc chia sẻ trong nhóm.

Kế hoạch 3: Môi Trường Phát Triển Ngoại Tuyến (Đề Xuất cho Nhà Phát Triển)

Máy Chủ Phát Triển Địa Phương

Khởi động máy chủ phát triển, cho phép tiếp tục sử dụng ngay cả khi mất kết nối sau này:

npm run dev

Máy chủ phát triển mặc định lắng nghe cổng 8080, truy cập thông qua http://localhost:8080. Xem cấu hình môi trường phát triển tại webpack/dev.js.

Cấu Hình Nhiều Đặc tả API

Chỉnh sửa tệp dev-helpers/config-swagger.yaml, thêm nhiều đặc tả API cục bộ:

apis:
  - url: 'api-v1.json'
    name: 'API Phiên Bản 1'
  - url: 'api-v2.json'
    name: 'API Phiên Bản 2'

Khởi động lại máy chủ phát triển, thanh điều hướng trên cùng sẽ hiển thị menu thả xuống để chuyển đổi giữa các phiên bản API.

Bảng So Sánh Chức Năng

Chức Năng	Triển Khai Tệp tĩnh	Triển Khai Docker	Môi Trường Phát Triển
Chạy hoàn toàn ngoại tuyến			(Cần kết nối Internet lần đầu để cài đặt phụ thuộc)
Không cần cài đặt Node.js
Hỗ trợ kiểm thử API
Chuyển đổi giữa nhiều đặc tả
Tự động làm mới

Ghi Chú Giải Quyết Vấn Đề Thường Gặp

Xử Lý Vấn Đề Xung Đột Ngôn Ngữ

Nếu gặp lỗi xung đột ngôn ngữ khi kiểm thử API, hãy chỉnh sửa tệp cấu hình dist/init-swagger.js để thêm tham số:

window.onload = function() {
  const ui = SwaggerUIBundle({
    // ...cấu hình khác
    withCredentials: true,  // Kích hoạt chứng thực xung đột ngôn ngữ
    requestInterceptor: (req) => {
      req.headers['Access-Control-Allow-Origin'] = '*';
      return req;
    }
  });
};

Lỗi Hiển Thị Kiểu Dữ Liệu

Nếu giao diện hiển thị sai kiểu dữ liệu, thường là do vấn đề đường dẫn tài nguyên tĩnh. Đảm bảo thư mục dist chứa các thư mục css và js đầy đủ, và các tham chiếu tài nguyên trong index.html chính xác. Xem mã nguồn kiểu tại style/main.scss.

Tối Ưu Hóa Tải Tệp Lớn

Với các tệp đặc tả API vượt quá 1MB, hãy kích hoạt nén:

gzip -k dist/api-nhanh.json

Và kích hoạt hỗ trợ nén gzip trên máy chủ Web (đã được cấu hình sẵn trong triển khai Docker).