API Docs Validator

Xác thực Tài liệu API

Tổng quan

Path: Thanh bên trái → API Document Validation 

Menu Type: Menu Nhóm (bao gồm các submenu) 

Tính năng Xác thực Tài liệu API cung cấp chức năng để xác thực định dạng và cấu trúc của các đặc tả API và theo dõi trạng thái xác thực. 

Cách truy cập

1. Nhấp vào menu API Document Validation trong thanh bên trái để mở rộng các submenu.
2. Chọn chức năng mong muốn từ danh sách submenu đã mở rộng.

💡 Lưu ý: Vì Xác thực Tài liệu API là một menu nhóm, nhấp vào nó sẽ chuyển đổi giữa việc mở rộng và thu gọn submenu.

Cấu trúc Submenu

Khi người dùng nhấp vào menu Xác thực Tài liệu API, các submenu sau đây được hiển thị: 

1. API Document Settings – Cấu hình quy tắc xác thực API
2. API Document Status Dashboard – Xem và theo dõi trạng thái xác thực

---

Cài đặt Tài liệu API

Tổng quan Tính năng

Trang Cài đặt Tài liệu API cho phép người dùng xác định, quản lý và áp dụng các bộ quy tắc xác thực cho API Docs Validator. Nó hỗ trợ chất lượng tài liệu API tiêu chuẩn bằng cách cho phép người dùng tạo các bộ quy tắc tùy chỉnh, cấu hình các chức năng xác thực và ánh xạ chúng đến các dự án cụ thể.

Cấu trúc Trang

Main Section

1. API Docs Validator Setting
   • Quản lý bộ quy tắc
   • Ánh xạ dự án
2. Validation Ruleset Management
   • Xem và quản lý danh sách các bộ quy tắc hiện có

• Add New Ruleset nút

1. Project Selection
   • Chọn một dự án cụ thể bằng cách sử dụng menu thả xuống dự án

Tính Năng Chính

• Validation Ruleset Management: Tạo, chỉnh sửa và xóa các bộ quy tắc xác thực
• Add New Ruleset: Tạo các bộ quy tắc mới bằng cách sử dụng các mẫu đã định nghĩa sẵn và tùy chỉnh các chức năng xác thực bằng cách thêm hoặc xóa chúng
• Project Mapping: Liên kết các bộ quy tắc xác thực với các dự án cụ thể
• Default Rulesets
  • OWASP Top10: Các quy tắc xác thực dựa trên 10 lỗ hổng bảo mật hàng đầu của OWASP
  • OAS(2.X, 3.X): Các quy tắc xác thực cho Đặc tả OpenAPI

Cách Sử Dụng

1. Nhấp vào menu API Document Validation ở thanh bên trái để mở rộng menu con
2. Chọn API Document Settings trong menu con
3. Chọn một dự án từ menu thả xuống Project (Tùy chọn)
4. Xem hoặc quản lý các bộ quy tắc hiện có trong phần Validation Ruleset Management
5. Nhấp vào Add New Ruleset để tạo một bộ quy tắc xác thực mới
   • Khi nhấp vào Add New Ruleset, một hộp thoại modal xuất hiện với ba mẫu:
     • Default Rule
     • Basic Rule
     • Advanced Rule
   • Nhập Thông Tin Bộ Quy Tắc: Nhập Tên Bộ Quy Tắc, Mô Tả
   • Chọn một mẫu và tùy chỉnh các chức năng xác thực của nó:
     • Mở Functions List để xem tất cả các chức năng xác thực có trong mẫu
     • Xóa các chức năng hiện có bằng cách xóa chúng khỏi trình soạn thảo và nhấp vào các chức năng để thêm chức năng mới từ danh sách chức năng có sẵn
     • Di chuột qua tên chức năng để xem mô tả ngắn
     • Nhấp vào liên kết bên dưới danh sách chức năng để mở nó trong một tab mới
6. Nhấp vào nút Save để thêm mục mới vào danh sách quản lý bộ quy tắc.

Các Loại Bộ Quy Tắc

• OWASP Top10: Xác thực 10 lỗ hổng bảo mật ứng dụng web hàng đầu
• OAS(2.X, 3.X): Validates OpenAPI Specification versions 2.x and 3.x

Cảnh báo

• ⚠️ Các thay đổi đối với bộ quy tắc phải được lưu để có hiệu lực
• ⚠️ Phân bổ dự án nên được sử dụng khi các quy tắc xác thực chỉ áp dụng cho các dự án cụ thể

---

Bảng điều khiển trạng thái tài liệu API

Mô tả tính năng

Bảng điều khiển trạng thái tài liệu API cho phép người dùng xem và theo dõi lịch sử thực thi xác thực định dạng API và kết quả.

Cấu trúc trang

Validation History Table

Hiển thị lịch sử thực thi xác thực dưới dạng bảng.

Tên cột	Mô tả
Người yêu cầu	Người đã yêu cầu xác thực
Tên dự án	Dự án mục tiêu
Tên API	API mục tiêu
Trạng thái	Trạng thái xác thực (Đạt / Không đạt, v.v.)
Số lượng lỗi	Số lỗi đã phát hiện
Nguyên nhân lỗi	Lý do xác thực không thành công
Thời gian xác thực	Ngày và giờ thực thi
Hành động	Xem chi tiết, chạy lại xác thực, v.v.

Tính năng chính

• View Validation History: Xem lại các lần thực thi xác thực trước đây
• Monitor Validation Status: Kiểm tra kết quả đạt/không đạt
• Error Analysis: Xem lại số lượng lỗi và nguyên nhân
• Filtering: Lọc theo dự án bằng cách sử dụng menu thả xuống dự án (tùy chọn)

Cách sử dụng

1. Nhấp vào menu API Document Validation ở thanh bên trái để mở rộng menu con
2. Chọn API Document Settings trong menu con
3. Kiểm tra lịch sử thực thi xác thực trong bảng Validation History.
4. Sử dụng menu thả xuống Project để chọn một dự án cụ thể để lọc (tùy chọn).
5. Sử dụng cột Actions của bảng để xem chi tiết hoặc thực hiện các hành động bổ sung

Chức năng bảng

• Pagination: Xem kết quả theo từng trang khi lịch sử lớn
• Sorting: Sắp xếp bằng cách nhấp vào tiêu đề cột (nếu được hỗ trợ)
• Detail View: Xem thông tin chi tiết qua cột Hành động

Mẹo sử dụng

• 💡 Project Filtering: Sử dụng menu thả xuống dự án để xem lịch sử xác thực cho một dự án cụ thể
• 💡 Status Check: Nhanh chóng xác định kết quả pass/fail qua cột Trạng thái
• 💡 Error Analysis: Sử dụng các cột Error Count và Error Cause để xác định các vấn đề xác thực
• 💡 Latest Data: Làm mới trang để xem kết quả xác thực gần nhất

---

Xác thực định dạng tài liệu Swagger

Tổng quan về tính năng

Xác thực định dạng tài liệu Swagger cho phép người dùng nhập các định nghĩa Swagger/OpenAPI và xác thực chúng theo các quy tắc đã cấu hình. Điều này giúp xác định các vấn đề tuân thủ tiêu chuẩn và lỗi trong các tài liệu Swagger trước khi triển khai.

Cấu trúc trang

1. Project Configuration Section

• Project Selection: Chọn dự án để xác thực
  • Ví dụ: otel-prj
• Các quy tắc xác thực đã áp dụng sẽ tự động được tải dựa trên dự án đã chọn

2. Applied Validation Rules Section

Hiển thị các bộ quy tắc và quy tắc đã áp dụng cho dự án đã chọn:

• Ruleset Name: Tên của bộ quy tắc đã áp dụng (ví dụ: MCP Swagger)
• Applied Rules Examples:
  • mcp-operation-id-required: yêu cầu xác thực operationId
  • mcp-operation-id-style: xác thực kiểu operationId
• mcp-operation-summary-required: yêu cầu xác thực tóm tắt hoạt động
  • mcp-json-request-body: xác thực nội dung yêu cầu JSON
  • mcp-json-request-body-schema: xác thực sơ đồ nội dung yêu cầu JSON
  • Các quy tắc khác
• Rule count: Hiển thị tổng số quy tắc (ví dụ: “và N quy tắc bổ sung đã được áp dụng”)

3. Swagger JSON Input Section

• Input Field: Một khu vực văn bản lớn nơi người dùng có thể nhập các định nghĩa JSON Swagger/OpenAPI.
  • Thông điệp hướng dẫn mặc định: "Vui lòng nhập Swagger JSON"
  • Hỗ trợ các định nghĩa Swagger ở định dạng OpenAPI 3.0
• Load Sample Button: Một nút màu xanh nằm ở góc trên bên phải của trường nhập.
  • Tự động tải một định nghĩa Swagger mẫu (ví dụ: ví dụ Petstore) vào trường nhập
  • Cho phép người dùng xem lại định dạng đầu vào và thực hiện các xác thực thử nghiệm
• Validation Status Indicators: Hiển thị kết quả xác thực JSON bên dưới trường nhập.
  • JSON hợp lệ: Hiển thị với biểu tượng kiểm tra màu xanh khi định dạng JSON hợp lệ
  • Đặc tả OpenAPI: Hiển thị với biểu tượng kiểm tra màu xanh khi định nghĩa tuân thủ đặc tả OpenAPI
• Run Swagger Validation Button: Một nút lớn màu xanh nằm ở giữa dưới của trang.
  • Thực hiện tất cả các quy tắc xác thực đã cấu hình đối với JSON Swagger đã nhập
  • Xác thực bắt đầu ngay lập tức khi nhấp, và kết quả được hiển thị bên dưới
• Export Results Button: Một nút màu xanh nằm cạnh nút chạy xác thực
  • Cho phép người dùng xuất kết quả xác thực ra tệp

4. Validation Results Section

Sau khi xác thực được thực hiện, kết quả được hiển thị ở dưới cùng của trang.

Summary Information (Định dạng thẻ trên cùng):

• ERROR: Số lượng lỗi phát hiện, hiển thị trên nền đỏ
  • Ví dụ: 1 lỗi
• WARNING: Số lượng cảnh báo phát hiện, hiển thị trên nền cam
  • Ví dụ: 0 cảnh báo
• SUCCESS: Số lượng xác thực thành công, hiển thị trên nền xanh
  • Ví dụ: 8 thành công
• FAIL - Total N Issues: Tổng số vấn đề xác thực, hiển thị với nhãn đỏ
  • Ví dụ: THẤT BẠI - Tổng 1 vấn đề

Detailed Results Table:

Tên cột	Mô tả
Mức độ nghiêm trọng	Hiển thị LỖI (đỏ) hoặc THÀNH CÔNG (xanh)
Quy tắc	Tên quy tắc xác thực đã áp dụng (Ví dụ: mcp-json-request-body)
Thông điệp	Thông điệp kết quả xác thực (Ví dụ: thuộc tính "nội dung" phải có...)
Đường dẫn	Đường dẫn trong định nghĩa Swagger nơi xảy ra lỗi
Tên bộ quy tắc	Tên của bộ quy tắc mà quy tắc thuộc về
Hành động	Xem thông tin chi tiết cho từng mục bằng cách nhấp vào nút “View Detail”

Table function:

• Pagination: Hiển thị kết quả theo từng trang khi có khối lượng lớn kết quả xác thực (ví dụ: “Số hàng mỗi trang: 10”)
• Sorting: Sắp xếp kết quả bằng cách nhấp vào tiêu đề cột
• Detail View: Nhấp vào nút View Details trong cột Action để xem thông tin chi tiết cho từng mục xác thực

Tính năng chính

1. Apply Project-specific validation rules

• Khi một dự án được chọn, các quy tắc xác thực được ánh xạ đến dự án đó sẽ tự động được áp dụng.
• Các quy tắc xác thực khác nhau có thể được áp dụng cho từng dự án.

2. Swagger JSON input and validation

• Định nghĩa Swagger/OpenAPI của API đã phát triển có thể được nhập trực tiếp để xác thực.
• Kiểm tra tính hợp lệ của định dạng JSON và tuân thủ thông số kỹ thuật OpenAPI theo thời gian thực.

3. Sample load function

• Nhấp vào nút Sample Load sẽ tự động nhập một định nghĩa Swagger mẫu.
• Mẫu này có thể được sử dụng để kiểm tra định dạng đầu vào cần thiết và thử nghiệm chức năng.

4. Run validation and view results

• Nhấp vào nút Run Swagger Validation để chạy tất cả các quy tắc xác thực đã cấu hình.
• Kết quả xác thực được phân loại thành Lỗi, Cảnh báo hoặc Đạt.
• Thông tin chi tiết cho từng mục xác thực (quy tắc, thông điệp, đường dẫn) có thể được xem.

5. Export results

• Kết quả xác thực có thể được xuất dưới dạng tệp để tài liệu hoặc chia sẻ.

Cách Sử Dụng

Basic Validation Process

1. Select Project: Từ menu thả xuống project to be validated ở trên cùng, chọn dự án cần được xác thực.
2. Check Validation Rules: Kiểm tra danh sách các quy tắc trong phần Applied Validation Rules.
3. Enter Swagger JSON:
   • Method 1: Sao chép Swagger JSON của API đã phát triển và dán vào trường nhập liệu.
   • Method 2: Nhấp vào nút Load Sample để tải một mẫu Swagger và chỉnh sửa nó.
4. Check JSON Validity: Ở dưới cùng của trường nhập liệu, kiểm tra các chỉ báo cho Valid JSON và OpenAPI Spec.
5. Run Validation: Nhấp vào nút Run Swagger Validation.
6. Review Results: Trong phần Validation Results ở dưới cùng, kiểm tra cả thông tin tóm tắt và kết quả chi tiết.
7. Fix Errors: Nếu phát hiện lỗi, tham khảo thông điệp và thông tin đường dẫn để sửa đổi định nghĩa Swagger.
8. Re-validate: Sau khi sửa chữa, chạy xác thực lại để xác nhận rằng tất cả các lỗi đã được giải quyết.

Các Tình Huống Sử Dụng Thực Tế

Scenario 1: Swagger Validation After Development Completion

1. Sau khi hoàn thành phát triển API, tạo định nghĩa Swagger/OpenAPI.
2. Điều hướng đến API Management > API Format Validation từ thanh bên trái.
3. Chọn dự án cần được xác thực trong phần project to be validated.
4. Sao chép Swagger JSON đã tạo, và dán vào trường nhập liệu.
5. Nhấp vào nút Run Swagger Validation.
6. Xem xét kết quả và sửa bất kỳ lỗi nào.
7. Lặp lại cho đến khi tất cả các xác thực đều thành công.

Scenario 2: Validation Test Using Sample 

1. Chọn project to be validated.
2. Nhấn nút Load Sample để tải Swagger mẫu.
3. Sử dụng Swagger mẫu làm tài liệu tham khảo để viết định nghĩa Swagger thực tế.
4. Nhấn nút Run Swagger Validation để xác thực.
5. Xem xét kết quả và thực hiện các sửa đổi cần thiết.

Scenario 3: Validation Rule Compliance Check  

1. Chọn dự án để kiểm tra các quy tắc xác thực đã áp dụng.
2. Nhập Swagger JSON.
3. Chạy xác thực.
4. Trong  Detailed results table, kiểm tra kết quả xác thực cho từng quy tắc.
5. Xem xét các quy tắc có ERROR và WARNING và sửa chúng.
6. Nhấn nút View Details để xem thêm thông tin về các lỗi.

Ví dụ sử dụng

Example 1: Basic Validation Execution 

1. Chọn dự án otel-prj
2. Nhấn Load Sample để tải Swagger mẫu
3. Nhấn Run Swagger Validation
4. Kiểm tra kết quả xác thực:
   • Lỗi: 1
   • Cảnh báo: 0
   • Đã vượt qua: 8

Example 2: Actual Swagger Validation 

1. Sao chép Swagger JSON của API đã hoàn thành
2. Chọn dự án (Ví dụ: otel-prj)
3. Dán Swagger JSON vào trường nhập
4. Kiểm tra tính hợp lệ của JSON (kiểm tra JSON hợp lệ, OpenAPI Spec)
5. Nhấn nút Run Swagger Validation 
6. Xem xét các lỗi trong kết quả xác thực:
   • Ví dụ: Vi phạm quy tắc mcp-json-request-body
   • Thông điệp: "content" property phải có thuộc tính yêu cầu "application/json"
   • Đường dẫn: paths./pet/{petId}/uploadImage.post.requestBody.content
7. Sửa lỗi của đường dẫn này trong định nghĩa Swagger
8. Chạy lại xác thực sau khi sửa
9. Xác nhận tất cả các xác thực đều vượt qua

Example 3: Validation Result Analysis 

1. Sau khi chạy xác thực, kiểm tra phần Validation Results 
2. Kiểm tra tổng số vấn đề trong summary information (Ví dụ: FAIL - Tổng cộng 1 vấn đề)
3. Trong Detailed results table, kiểm tra từng mục: 
   • Severity: kiểm tra ưu tiên các mục có ERROR
   • Rule: kiểm tra quy tắc nào đã thất bại

• Message: kiểm tra chi tiết lỗi cụ thể
  • Path: kiểm tra vị trí chính xác trong định nghĩa Swagger cần sửa

1. Nhấp vào View Details để biết thêm thông tin
2. Sửa lỗi và chạy lại xác thực

Cảnh báo

• ⚠️ Project Selection Required: Vì các quy tắc xác thực có thể khác nhau cho mỗi dự án, dự án chính xác phải được chọn.
• ⚠️ JSON Format Compliance: Swagger đã nhập phải ở định dạng JSON hợp lệ và phải tuân thủ thông số kỹ thuật OpenAPI.
• ⚠️ Validation Rule Review: Kiểm tra các quy tắc xác thực áp dụng cho dự án trước và chuẩn bị Swagger sao cho tất cả các mục yêu cầu được tuân thủ đúng cách.
• ⚠️ Re-validation After Fixing: Sau khi sửa lỗi, hãy chắc chắn chạy lại xác thực để xác nhận rằng tất cả các vấn đề đã được giải quyết.
• ⚠️ Save Validation Results: Sử dụng chức năng xuất result để lưu kết quả xác thực quan trọng.

Mẹo sử dụng

• 💡 Use Samples: Đối với lần sử dụng đầu tiên, hãy sử dụng nút load sample để kiểm tra định dạng đầu vào yêu cầu.
• 💡 Real-time Validation: Trong khi nhập JSON, hãy kiểm tra các chỉ báo JSON hợp lệ và thông số kỹ thuật OpenAPI để xác thực theo thời gian thực.
• 💡 Rule-based Filtering: Bảng kết quả xác thực có thể được lọc theo quy tắc để chỉ xem các kết quả cho một quy tắc xác thực cụ thể.
• 💡 Path Utilization: Thông tin đường dẫn trong kết quả xác thực có thể được sử dụng để xác định vị trí chính xác trong định nghĩa Swagger và sửa chữa nó.
• 💡 Repeated validation: Chạy xác thực định kỳ trong quá trình phát triển là hiệu quả để phát hiện và giải quyết lỗi sớm.