Giao diện

Cài đặt và sử dụng — API Doc ​

Tổng quan ​

Plugin tự động sinh tài liệu API theo chuẩn Swagger/OpenAPI 3.0 từ các resources, actions và collections đã đăng ký trong hệ thống. Developer truy cập Swagger UI tương tác để duyệt, thử nghiệm API và tải xuống spec.

Yêu cầu hệ thống ​

  • Server Digiforce đang chạy
  • Quyền Admin để truy cập trang Settings

Bước 1: Kích hoạt plugin ​

Vào Settings → Plugin Manager, tìm plugin-api-doc và bật. Khởi động lại server.

Bước 2: Truy cập tài liệu API ​

Sau khi bật plugin, có hai cách truy cập:

Cách truy cậpURLGhi chú
Swagger UI (giao diện đồ hoạ)https://your-domain/api-documentationDuyệt endpoint, thử gọi API
Qua SettingsSettings → API DocumentationEntry point chính trong admin

Giao diện Swagger UI ​

Swagger UI hiển thị toàn bộ API được tổ chức theo namespace:

NamespaceMô tảVí dụ endpoint
coreAPI lõi: xác thực, metadata ứng dụng/api/auth:signIn, /api/app:getLang
pluginsAPI do plugin đăng ký resource riêng/api/roles:list, /api/workflows:trigger
collectionsAPI CRUD tự sinh cho mỗi collection/api/posts:list, /api/posts:create

Bước 3: Sử dụng Swagger UI ​

Duyệt API endpoints ​

  1. Chọn namespace từ dropdown phía trên
  2. Mở rộng endpoint muốn xem
  3. Xem chi tiết parameters, request body, response schema

Thử gọi API (Try it out) ​

  1. Nhấn nút Try it out trên endpoint bất kỳ
  2. Điền parameters và request body
  3. Nhấn Execute để gửi request thực
  4. Xem response trực tiếp trong giao diện

Xác thực cho API cần đăng nhập ​

  1. Nhấn nút Authorize (biểu tượng khoá) phía trên
  2. Nhập Bearer token: Bearer <your-token>
  3. Sau đó có thể thử tất cả API cần xác thực

Tải xuống OpenAPI spec ​

bash
# Lấy danh sách namespaces
curl https://your-domain/api/swagger:getUrls

# Lấy OpenAPI spec cho namespace cụ thể
curl https://your-domain/api/swagger:get?ns=collections

Cấu hình ​

Tham sốMặc địnhMô tả
Enable Swagger UItrueBật/tắt giao diện Swagger UI
Base Path/apiĐường dẫn gốc của API
TitleDigiforce APITiêu đề hiển thị trên Swagger UI
Version1.0.0Phiên bản API hiển thị

Luồng sinh tài liệu ​

TIP

Spec được sinh lazy — chỉ tạo khi client yêu cầu. Không ảnh hưởng hiệu năng server khi không dùng.

Tích hợp với CI/CD ​

Tải OpenAPI spec tự động để sinh client SDK hoặc kiểm tra contract:

bash
# Tải spec cho collections
curl -o openapi-collections.json \
  "https://your-domain/api/swagger:get?ns=collections"

# Sinh TypeScript client từ spec
npx openapi-typescript openapi-collections.json -o ./types/api.ts

Bảo mật và khuyến nghị ​

Cảnh báo bảo mật

  • Không nên bật Swagger UI trên môi trường production công khai
  • Nếu cần bật, giới hạn truy cập bằng IP restriction hoặc VPN
  • API doc hiển thị cấu trúc endpoint và schema — không hiển thị dữ liệu thực
  • Chỉ admin mới truy cập được trang API Documentation trong Settings

Lưu ý ​

  • API doc tự động cập nhật khi thêm collections hoặc resources mới — không cần thao tác thủ công
  • Hỗ trợ cả built-in resources (từ core) và custom resources (từ plugin bên thứ ba)
  • Plugin sử dụng swagger-ui-dist để render giao diện Swagger
  • Phân quyền qua ACL snippet pm.api-doc.documentation — chỉ Admin