5s.openapi.standard

✅ Checklist Tiêu Chuẩn 5★ Toàn Diện cho File `openapi` Service¶

Một file openapi (ví dụ: openapi.yaml hoặc openapi.json) được đánh giá 5 sao cần đảm bảo các yếu tố sau, giúp định nghĩa hợp đồng API một cách rõ ràng, chính xác, dễ sử dụng và dễ quản lý:

1. 📜 Đặc Tả API Hoàn Chỉnh và Chính Xác (Completeness & Accuracy of API Specification):

2. 🧩 Định nghĩa Schema và Tái sử dụng (Schema Definitions & Reusability - components/schemas):

Tối ưu Schema với $ref: Đảm bảo toàn bộ request/response body và các phần lặp lại của schema sử dụng tham chiếu $ref đến các định nghĩa trong components/schemas, tránh định nghĩa inline lặp đi lặp lại.
Mô tả Schema Chi tiết: Mỗi schema trong components/schemas phải có description, type, và example (nếu phù hợp). Các thuộc tính (properties) của schema cũng cần description và example.
Sử dụng readOnly/writeOnly: Đánh dấu các trường chỉ đọc hoặc chỉ ghi một cách chính xác.
Định nghĩa ENUM tập trung: Tất cả các ENUM nên được định nghĩa là các schema riêng biệt trong components/schemas và được tham chiếu, thay vì hardcode giá trị trực tiếp trong đặc tả endpoint.
Sử dụng nullable: true (cho OpenAPI 3.0) hoặc nullable trong type array (cho OpenAPI 3.1+): Cho các trường tùy chọn có thể nhận giá trị null.
Sử dụng oneOf, allOf, anyOf (nếu cần): Cho các schema phức tạp có nhiều biến thể hoặc cần kết hợp từ các schema khác.

3. 🔐 Bảo Mật và Phân Quyền Rõ Ràng (Clear Security & Authorization Definition):

Cơ chế xác thực (Authentication): Định nghĩa rõ ràng các securitySchemes được sử dụng trong components/securitySchemes (ví dụ: bearerAuth cho JWT). Áp dụng security scheme cho toàn bộ API hoặc từng operation cụ thể.
Yêu cầu quyền (Permissions/RBAC):
- Sử dụng custom extension như x-required-permission để chỉ định permission cần thiết cho từng operation quan trọng.
- Permission code nên nhất quán và dễ hiểu, lý tưởng nhất là trùng với ENUM hoặc hằng số từ hệ thống RBAC template.

4. ✨ Ví dụ Minh Họa Thực Tế (Practical Examples):

Cung cấp các ví dụ (example hoặc examples) phong phú cho request parameters, request body, và response body trong đặc tả.
Ví dụ nên bao gồm cả kịch bản thành công và một số lỗi thường gặp (nếu có thể, đặc biệt cho các API phức tạp).

5. 🛠️ Tuân Thủ Chuẩn và Công Cụ (Adherence to Standards & Tooling):

Chuẩn OpenAPI: Tuân thủ chặt chẽ phiên bản OpenAPI đã chọn (ví dụ: 3.0.3, 3.1.0).
Tính hợp lệ (Validation): File đặc tả phải hợp lệ và vượt qua kiểm tra của các công cụ linter/validator (ví dụ: Spectral).
Khả năng Sinh Code/Docs: Viết theo cách dễ dàng cho việc tự động sinh client SDKs, server stubs, và tài liệu API tương tác (ví dụ: Swagger UI, Redoc).
Nhất quán với ADRs hệ thống: Phản ánh đúng các quyết định kiến trúc liên quan đến API (ví dụ: ADR-009 API Governance, ADR-011 API Error Format, ADR-012 Response Structure, ADR-013 Path Naming Convention).

6. 📄 Thông Tin Bổ Sung và Quản Trị (Supplementary Information & Governance):

Chính sách Versioning & Deprecation: Mô tả cách API được version hóa và chính sách loại bỏ phiên bản cũ (có thể tham chiếu đến ADR liên quan).
Thông tin Rate Limiting (nếu có): Mô tả giới hạn số lần gọi API.
Metadata quản trị tài liệu:
- Ghi chú ngày tạo/cập nhật, phiên bản của chính file OpenAPI (có thể qua version control của Git).
- Thông tin tác giả, người review (có thể quản lý ngoài file spec, ví dụ trong commit history hoặc tài liệu đi kèm).
Liên kết đến tài liệu liên quan: Trong phần description của API hoặc của Info Object, có thể cung cấp link đến file design chi tiết, data model, hoặc các ADRs liên quan.
Custom Extensions (x-...):
- Nếu sử dụng các extension tùy chỉnh (ví dụ: x-required-permission, x-audit-action, x-emits-event), chúng cần được giải thích rõ ràng mục đích và cách sử dụng (có thể trong phần mô tả chung hoặc trong một tài liệu hướng dẫn riêng).

🎯 `x-extensions` chuẩn hóa cho toàn hệ thống `dx-vas`¶

Các x-extensions dưới đây được sử dụng để mô tả các đặc điểm logic nội bộ (RBAC, điều kiện runtime, trace, v.v.) và sẽ được chuẩn hóa trên toàn bộ các OpenAPI spec của hệ thống dx-vas. Những extension này được API Gateway sử dụng để thực hiện phân quyền, định tuyến và quan sát (observability) trong runtime.

✅ Quy tắc sử dụng:¶

Chỉ dùng trong các field hợp lệ theo OpenAPI 3.x: paths, operation, tags, info, v.v.
Không được khai báo dưới block components:
Không dùng như schema để $ref
Cần có ví dụ, mô tả rõ ràng, và thống nhất toàn hệ thống

🔒 `x-required-permission`¶

x-required-permission: "user.read"

Mô tả: Mã permission yêu cầu mà người dùng phải có để truy cập route này.
Xử lý: Gateway sẽ kiểm tra permission có nằm trong Redis key rbac:{user_id}:{tenant_id} không.
Áp dụng tại: paths, paths.[path].[method]

🧩 `x-condition`¶

x-condition:
  user_id: "{{X-User-ID}}"
  tenant_id: "{{X-Tenant-ID}}"

Mô tả: Điều kiện logic ngữ cảnh runtime. Có thể dùng placeholder dạng {{HEADER_NAME}}.
Xử lý: Gateway sẽ so sánh giá trị thực tế với điều kiện này để cho phép/deny truy cập.
Áp dụng tại: paths, paths.[path].[method]

✅ `x-gateway-enforced`¶

x-gateway-enforced: true

Mô tả: Đánh dấu route này có được kiểm soát bởi Gateway (RBAC, trace, condition) hay không.
Xử lý: Nếu false, route sẽ được forward raw, không kiểm soát.
Áp dụng tại: paths, paths.[path].[method]

📊 `x-route-evaluation`¶

x-route-evaluation: "check-permission + forward"

Mô tả: Ghi chú logic xử lý của route – phục vụ testing, observability, analytics.
Giá trị gợi ý: check-permission, check-condition, introspect-token, forward-only, ...
Áp dụng tại: paths, paths.[path].[method]

🔐 `x-internal` (đã dùng trong tags)¶

x-internal: true

Mô tả: Gắn nhãn nhóm API chỉ dành cho nội bộ, không xuất hiện trong public docs.
Áp dụng tại: tags[]

📌 Mọi service khi sử dụng các x-extensions này cần tuân thủ chính tả, format và ngữ nghĩa chuẩn như trên. Gateway và hệ thống kiểm thử CI sẽ reject nếu không đạt chuẩn.

5s.openapi.standard

✅ Checklist Tiêu Chuẩn 5★ Toàn Diện cho File openapi Service¶

🎯 x-extensions chuẩn hóa cho toàn hệ thống dx-vas¶

✅ Quy tắc sử dụng:¶

🔒 x-required-permission¶

🧩 x-condition¶

✅ x-gateway-enforced¶

📊 x-route-evaluation¶

🔐 x-internal (đã dùng trong tags)¶