@digiforce-nc/plugin-api-doc

Plugin tự động sinh tài liệu API theo chuẩn Swagger/OpenAPI — dựa trên collection schema và resource actions đã đăng ký, cung cấp giao diện Swagger UI tương tác.

Plugin này làm gì?

Thay vì viết tài liệu API thủ công, plugin quét toàn bộ collection và resource endpoint, sinh ra OpenAPI 3.0 spec tự động. Developer truy cập Swagger UI để xem và thử nghiệm API trực tiếp.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Quét schema	SwaggerManager duyệt tất cả collection fields, associations, resource actions
2	Sinh OpenAPI spec	Tạo paths, schemas, parameters, responses theo chuẩn OpenAPI 3.0
3	Swagger UI	Trang Settings + route `/api-documentation` nhúng Swagger UI tương tác

Kiến trúc

Tổng quan

Tầng	Vai trò	Thành phần
Client UI	Hiển thị Swagger UI, chọn namespace	Settings entry, `/api-documentation` route
Server	Resource `swagger` với actions `get`, `getUrls`	`PluginAPIDocServer`
SwaggerManager	Quét schema, sinh OpenAPI spec	Core logic phía server
Namespaces	Phân nhóm API theo nguồn	`core`, `plugins`, `collections`

Namespace system

Namespace	Mô tả	Ví dụ
`core`	API lõi: auth, app metadata	`/api/auth:signIn`, `/api/app:getLang`
`plugins`	API do plugin đăng ký resource riêng	`/api/roles:list`, `/api/workflows:trigger`
`collections`	API CRUD tự sinh cho mỗi collection	`/api/posts:list`, `/api/posts:create`

Luồng sinh tài liệu

Vòng đời plugin

ACL - Phân quyền

ACL snippet	Quyền	Mô tả
`pm.api-doc.documentation`	Admin	Truy cập trang tài liệu API trong Settings

Ví dụ sử dụng API

Lấy danh sách namespaces

typescript

const response = await agent.resource('swagger').getUrls();
// [{ name: 'core', url: '...' }, { name: 'plugins', url: '...' }, ...]

Lấy OpenAPI spec cho namespace

typescript

const response = await agent.resource('swagger').get({
  filter: { ns: 'collections' },
});
// spec.openapi = '3.0.0'
// spec.paths = { '/api/posts:list': { get: {...} }, ... }

Truy cập Swagger UI trên trình duyệt

https://your-app.com/api-documentation

Swagger UI cho phép duyệt endpoint, thử gọi API (Try it out), xem schema chi tiết, tải xuống OpenAPI spec.

Thành phần client

Thành phần	Mô tả
`APIDocSettings`	Entry trong Settings → "API Documentation"
`SwaggerUIPage`	Trang nhúng Swagger UI với namespace selector
`APIDocExport`	Nút xuất OpenAPI spec (JSON)

Dependencies

Package	Vai trò
`swagger-ui-dist`	Thư viện Swagger UI frontend
`@digiforce-nc/server`	Server framework — resource registration
`@digiforce-nc/database`	Database ORM — đọc collection schema
`@digiforce-nc/client`	Client framework — đăng ký Settings entry