Giao diện

Câu hỏi thường gặp (FAQ) — API Doc ​

Sử dụng ​

Swagger UI không hiển thị? ​

Kiểm tra theo thứ tự:

  1. Plugin đã bật: Vào Settings → Plugin Manager, kiểm tra plugin-api-doc đang active
  2. Server đã khởi động lại: Sau khi bật plugin, cần restart server
  3. URL đúng: Truy cập /api-documentation (không phải /api/swagger)
  4. Cấu hình: Kiểm tra Enable Swagger UI = true trong cấu hình plugin

API của custom collection không xuất hiện trong Swagger? ​

  • Swagger tự động cập nhật khi tạo collection mới — thử refresh trang
  • Kiểm tra collection đã được publish (không ở trạng thái draft)
  • Nếu collection vừa tạo, đợi vài giây để SwaggerManager quét lại
  • Spec được sinh lazy — lần đầu truy cập namespace mới có thể mất vài giây

Làm sao thử API cần đăng nhập từ Swagger UI? ​

  1. Đăng nhập vào Digiforce qua giao diện bình thường
  2. Mở Developer Tools → Network → copy Bearer token từ request header
  3. Trong Swagger UI, nhấn Authorize → dán token
  4. Sau đó có thể Try it out trên mọi endpoint cần xác thực

Có thể export OpenAPI spec ra file không? ​

Có. Sử dụng API trực tiếp:

bash
# Lấy tất cả namespaces khả dụng
curl https://your-domain/api/swagger:getUrls

# Tải spec của namespace collections
curl -o spec.json "https://your-domain/api/swagger:get?ns=collections"

File JSON trả về tuân thủ chuẩn OpenAPI 3.0 — có thể import vào Postman, Insomnia, hoặc dùng để sinh client SDK.

Spec có bao gồm tất cả API trong hệ thống không? ​

Spec được chia theo namespace:

NamespaceBao gồm
coreAPI xác thực, app metadata, system endpoints
pluginsAPI từ tất cả plugin đã cài (roles, workflows, users...)
collectionsAPI CRUD cho tất cả collection (kể cả custom)

Mỗi namespace sinh spec riêng — tải namespace cần thiết thay vì toàn bộ.

Bảo mật ​

Nên bật Swagger UI trên production không? ​

Không khuyến nghị. Swagger UI hiển thị toàn bộ cấu trúc API — kẻ tấn công có thể dùng thông tin này để tìm lỗ hổng. Nếu bắt buộc cần trên production:

  • Giới hạn truy cập bằng IP whitelist
  • Đặt sau VPN hoặc reverse proxy có authentication
  • Chỉ mở tạm thời khi cần, tắt khi xong

API doc có lộ thông tin nhạy cảm không? ​

  • Không hiển thị dữ liệu thực — chỉ hiển thị cấu trúc endpoint, parameters và schema
  • Có thể lộ tên field nhạy cảm — ví dụ: tên collection salaries, field creditCardNumber
  • Giải pháp: Giới hạn truy cập Swagger UI, hoặc cấu hình loại trừ collection nhạy cảm

Ai có quyền truy cập API Documentation? ​

Chỉ user có role Admin — plugin đăng ký ACL snippet pm.api-doc.documentation giới hạn truy cập cho admin. User thường không thấy mục này trong Settings.