Hướng Dẫn 5 Bước Xây Dựng Giao Diện Swagger UI Tùy Chỉnh: Từ Thiết Kế Đến Triển Khai

Swagger UI là một công cụ mạnh mẽ để tạo tài liệu API tương tác, giúp nhà phát triển xây dựng tài liệu API nhanh chóng. Bài viết này sẽ hướng dẫn bạn qua 5 bước đơn giản để tạo giao diện Swagger UI tùy chỉnh, giúp tài liệu API của bạn vừa đẹp mắt vừa hữu ích.

1. Hiểu về kiến trúc cơ bản của Swagger UI

Trước khi bắt đầu tùy chỉnh, bạn cần hiểu về kiến trúc cơ bản của Swagger UI. Swagger UI sử dụng thiết kế theo mô-đun, tất cả các chức năng cốt lõi đều được thực hiện thông qua plugin. Bạn có thể tìm thấy các plugin tích hợp trong thư mục src/core/plugins/, cung cấp đầy đủ chức năng từ xác thực đến xử lý yêu cầu.

Swagger UI 2 và Swagger UI 3 có sự khác biệt rõ rệt về thiết kế giao diện. Swagger UI 2 sử dụng màu xanh làm chủ đạo, bố cục khá gọn gàng:

Trong khi Swagger UI 3 áp dụng thiết kế hiện đại hơn, giao diện rõ ràng hơn, phân chia khu vực chức năng hợp lý hơn:

2. Thiết lập môi trường phát triển

Để bắt đầu tùy chỉnh giao diện Swagger UI, trước tiên bạn cần thiết lập môi trường phát triển. Thực hiện theo các bước sau:

Sao chép kho lưu trữ:

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

Cài đặt các dependency:

cd swagger-ui
npm install

Khởi động máy chủ phát triển:

npm run dev

Sau khi máy chủ phát triển khởi động, bạn có thể truy cập http://localhost:3200 trong trình duyệt để xem giao diện Swagger UI mặc định.

3. Tạo plugin tùy chỉnh

Hệ thống plugin là cốt lõi của Swagger UI, cho phép mở rộng chức năng thông qua việc tạo plugin. Plugin có thể chứa quản lý trạng thái, component React và các hàm chung.

Các bước cơ bản để tạo plugin:

Tạo thư mục plugin mới trong src/core/plugins/, ví dụ plugin-custome-cua-toi.
Tạo file入口 của plugin index.js, cấu trúc cơ bản như sau:

export function PluginCuaToi(toolbox) {
  return {
    statePlugins: {
      // Mã quản lý trạng thái
    },
    components: {
      // Component React
    },
    fn: {
      // Các hàm chung
    }
  }
}

Thêm component tùy chỉnh vào plugin, ví dụ:

components: {
  ComponentCuaToi: () => <div>Đây là component tùy chỉnh của tôi</div>
}

Hướng dẫn chi tiết về phát triển plugin có thể tham khảo tài liệu chính thức docs/customization/add-plugin.md.

4. Tích hợp component tùy chỉnh

Sau khi tạo plugin, bạn cần tích hợp nó vào Swagger UI:

Thêm plugin vào cấu hình:

SwaggerUI({
  url: 'dia-chi-api-cua-ban',
  plugins: [PluginCuaToi]
})

Nếu muốn sửa đổi plugin cốt lõi, bạn có thể thêm nó vào preset cơ bản: src/core/presets/base/index.js
Sử dụng component tùy chỉnh tại nơi cần thiết, ví dụ trong component bố cục:

import { ComponentCuaToi } from 'plugin-custome-cua-toi'

function BoCucCuaToi() {
  return (
    <div>
      <ComponentCuaToi />
      {/* Nội dung khác */}
    </div>
  )
}

5. Tùy chỉnh kiểu dáng và kiểm thử

Bước cuối cùng là tùy chỉnh kiểu dáng component và tiến hành kiểm thử:

Tạo file kiểu dáng tùy chỉnh trong thư mục src/style/, ví dụ _component-cua-toi.scss.
Nhập file kiểu dáng tùy chỉnh vào file kiểu dáng chính main.scss:

@import 'component-cua-toi';

Viết các bài kiểm thử đơn vị, đặt file kiểm thử trong thư mục test/unit/.
Chạy kiểm thử:

npm test

Xây dựng phiên bản sản xuất:

npm run build

Thông qua 5 bước trên, bạn có thể dễ dàng tạo và tích hợp component Swagger UI tùy chỉnh. Hệ thống plugin của Swagger UI cung cấp sự linh hoạt lớn, cho phép bạn tùy chỉnh giao diện tài liệu API độc đáo theo yêu cầu dự án. Dù là thêm chức năng mới hay sửa đổi kiểu dáng hiện có, mọi thứ đều có thể thực hiện thông qua hệ thống plugin mà không cần sửa đổi mã cốt lõi. Hãy bắt đầu xây dựng giao diện Swagger UI riêng của bạn ngay hôm nay!

Thẻ: Swagger UI API Documentation react Plugin Development Web Development

Đăng vào ngày 18 tháng 5 lúc 09:27

Thành phố Cuồng loạn

Hướng Dẫn 5 Bước Xây Dựng Giao Diện Swagger UI Tùy Chỉnh: Từ Thiết Kế Đến Triển Khai