API Docs Validator

📋 API Document Validation

Tổng quan

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

Menu Type: Group Menu (bao gồm các sub menu) 

Tính năng API Document Validation cung cấp chức năng để kiểm chứng định dạng và cấu trúc của các đặc tả API và theo dõi trạng thái kiểm chứng. 

How to Access

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

💡 Lưu ý: Vì API Document Validation là một Group Menu, nhấp vào nó sẽ chuyển đổi giữa việc mở rộng và thu gọn sub menu.

Submenu Structure

Khi người dùng nhấp vào menu API Document Validation, các sub menu sau đây được hiển thị: 

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

---

API Document Settings

Path: Left Sidebar > API Document Validation > API Document Settings

Feature Overview

Trang API Document Settings cho phép người dùng xác định, quản lý và áp dụng các Ruleset kiểm chứng 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 Ruleset tùy chỉnh, cấu hình các chức năng kiểm chứng và Mapping chúng đến các dự án cụ thể.

Page Structure

Main Section

1. API Docs Validator Setting
   • Quản lý Ruleset
   • Mapping dự án
2. Validation Ruleset Management
   • Xem và quản lý danh sách các Ruleset hiện có
   • Button Add New Ruleset
3. Project Selection
   • Chọn một dự án cụ thể bằng hướng dẫn sử dụng menu dropdown dự án

Tính Năng Chính

• Validation Ruleset Management: Tạo, chỉnh sửa và xóa các Ruleset kiểm chứng
• Add New Ruleset: Tạo các Ruleset mới bằng hướng dẫn sử dụng các template đã định nghĩa sẵn và tùy chỉnh các chức năng kiểm chứng bằng cách thêm hoặc xóa chúng
• Project Mapping: Liên kết các Ruleset kiểm chứng với các dự án cụ thể
• Default Rulesets
  • OWASP Top10: Các quy tắc kiểm chứng 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 kiểm chứng cho Đặc tả OpenAPI

Hướng dẫn sử dụng

1. Nhấp vào menu API Document Validation ở thanh bên trái để mở rộng sub menu
2. Chọn API Document Settings trong sub menu
3. Chọn một dự án từ menu dropdown Project (Tùy chọn)
4. Xem hoặc quản lý các Ruleset hiện có trong phần Validation Ruleset Management
5. Nhấp vào Add New Ruleset để tạo một Ruleset kiểm chứng mới
   • Khi nhấp vào Add New Ruleset, một hộp thoại modal xuất hiện với ba template:
     • Default Rule
     • Basic Rule
     • Advanced Rule
   • Nhập Thông Tin Ruleset: Nhập Tên Ruleset, Mô tả
   • Chọn một template và tùy chỉnh các chức năng kiểm chứng của nó:
     • Mở Functions List để xem tất cả các chức năng kiểm chứng có trong template
     • 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ý Ruleset.

Các Loại Ruleset

• OWASP Top10: Kiểm chứng 10 lỗ hổng bảo mật ứng dụng web hàng đầu
• OAS(2.X, 3.X): Kiểm chứng đặc tả OpenAPI phiên bản 2.x 3.x

Lưu ý

• ⚠️ Các thay đổi đối với Ruleset 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 kiểm chứng chỉ áp dụng cho các dự án cụ thể

---

API Document Status Dashboard

Path: Left Sidebar > API Document Validation > API Document Status Dashboard

Mô tả Tính năng

API Document Status Dashboard cho phép người dùng xem và theo dõi lịch sử thực thi kiểm chứng định dạng API và kết quả.

Page Structure

Validation History Table

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

Tên cột	Mô tả
Người yêu cầu	Người đã yêu cầu kiểm chứng
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 kiểm chứng (Đạt / Không đạt, v.v.)
Số lượng ERROR	Số lượng ERROR đã phát hiện
Nguyên nhân ERROR	Lý do kiểm chứng không SUCCESS
Thời gian kiểm chứng	Ngày và giờ thực thi
Hành động	Xem chi tiết, chạy lại kiểm chứng, v.v.

Tính năng chính

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

Hướng dẫn sử dụng

1. Nhấp vào menu API Document Validation ở thanh bên trái để mở rộng sub menu
2. Chọn API Document Settings trong sub menu
3. Kiểm tra lịch sử thực thi kiểm chứng trong bảng Validation History.
4. Sử dụng menu dropdown 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

Table Functions

• 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

Usage tips

• 💡 Project Filtering: Sử dụng menu dropdown dự án để xem lịch sử kiểm chứng 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 issue kiểm chứng
• 💡 Latest Data: Làm mới trang để xem kết quả kiểm chứng gần nhất

---

Swagger Document Format Validation

Path: Left Sidebar > API Document Validation > API Document Validation

Tổng quan Tính năng

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

Page Structure

1. Project Configuration Section

• Project Selection: Chọn dự án để kiểm chứng
  • Ví dụ: otel-prj
• Các quy tắc kiểm chứng đã á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 Ruleset và quy tắc đã áp dụng cho dự án đã chọn:

• Ruleset Name: Tên của Ruleset đã áp dụng (ví dụ: MCP Swagger)
• Applied Rules Examples:
  • mcp-operation-id-required: yêu cầu kiểm chứng operationId
  • mcp-operation-id-style: kiểm chứng kiểu operationId
  • mcp-operation-summary-required: yêu cầu kiểm chứng tóm tắt hoạt động
  • mcp-json-request-body: kiểm chứng nội dung yêu cầu JSON
  • mcp-json-request-body-schema: kiểm chứng 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 text area lớn nơi người dùng có thể nhập các định nghĩa JSON Swagger/OpenAPI.
  • Message 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 template (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 kiểm chứng thử nghiệm
• Validation Status Indicators: Hiển thị kết quả kiểm chứng 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 kiểm chứng đã cấu hình đối với Swagger JSON đã nhập
  • Kiểm chứng 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 button run validation
  • Cho phép người dùng xuất kết quả kiểm chứng ra tệp

4. Validation Results Section

Sau khi kiểm chứng đượ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 ERROR phát hiện, hiển thị trên nền đỏ
  • Ví dụ: 1 ERROR
• 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 kiểm chứng SUCCESS, hiển thị trên nền xanh
  • Ví dụ: 8 SUCCESS
• FAIL - Total N Issues: Tổng số issue kiểm chứng, hiển thị với nhãn đỏ
  • Ví dụ: FAIL - Tổng cộng 1 issue

Detailed Results Table:

Tên cột	Mô tả
Mức độ nghiêm trọng	Hiển thị ERROR (đỏ) hoặc SUCCESS (xanh)
Quy tắc	Tên quy tắc kiểm chứng đã áp dụng (Ví dụ: mcp-json-request-body)
Message	Message kết quả kiểm chứng (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 ERROR
Tên Ruleset	Tên của Ruleset 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ả kiểm chứng (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 kiểm chứng

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 kiểm chứng được Mapping đến dự án đó sẽ tự động được áp dụng.
• Các quy tắc kiểm chứng 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 để kiểm chứng.
• 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 template.
• template 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 kiểm chứng đã cấu hình.
• Kết quả kiểm chứng được phân loại thành ERROR, Cảnh báo hoặc Đạt.
• Thông tin chi tiết cho từng mục kiểm chứng (quy tắc, Message, đường dẫn) có thể được xem.

5. Export results

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

Hướng dẫn sử dụng

Basic Validation Process

1. Select Project: Từ menu dropdown project to be validated ở trên cùng, chọn dự án cần được kiểm chứng.
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 template 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 JSON hợp lệ 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 ERROR, tham khảo Message 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 kiểm chứng lại để xác nhận rằng tất cả các ERROR đã được giải quyết.

Practical Usage Scenarios

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 kiểm chứng 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ỳ ERROR nào.
7. Lặp lại cho đến khi tất cả các kiểm chứng đều SUCCESS.

Scenario 2: Validation Test Using Sample 

1. Chọn project to be validated.
2. Nhấn nút Load Sample để tải Swagger template.
3. Sử dụng Swagger template 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 để kiểm chứng.
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 kiểm chứng đã áp dụng.
2. Nhập Swagger JSON.
3. Chạy kiểm chứng.
4. Trong  Detailed results table, kiểm tra kết quả kiểm chứng 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 ERROR.

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 template
3. Nhấn Run Swagger Validation
4. Kiểm tra kết quả kiểm chứng:
   • ERROR: 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 ERROR trong kết quả kiểm chứng:
   • Ví dụ: Vi phạm quy tắc mcp-json-request-body
   • Message: "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 ERROR của đường dẫn này trong định nghĩa Swagger
8. Chạy lại kiểm chứng sau khi sửa
9. Xác nhận tất cả các kiểm chứng đều vượt qua

Example 3: Validation Result Analysis 

1. Sau khi chạy kiểm chứng, kiểm tra phần Validation Results 
2. Kiểm tra tổng số issue trong summary information (Ví dụ: FAIL - Tổng cộng 1 issue)
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 đã FAIL

• Message: kiểm tra chi tiết ERROR 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 ERROR và chạy lại kiểm chứng

Lưu ý

• ⚠️ Project Selection Required: Vì các quy tắc kiểm chứng 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 kiểm chứng á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 ERROR, hãy chắc chắn chạy lại kiểm chứng để xác nhận rằng tất cả các issue đã được giải quyết.
• ⚠️ Save Validation Results: Sử dụng chức năng xuất result để lưu kết quả kiểm chứng 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 để kiểm chứng theo thời gian thực.
• 💡 Rule-based Filtering: Bảng kết quả kiểm chứng có thể được lọc theo quy tắc để chỉ xem các kết quả cho một quy tắc kiểm chứng cụ thể.
• 💡 Path Utilization: Thông tin đường dẫn trong kết quả kiểm chứng 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 kiểm chứng định kỳ trong quá trình phát triển là hiệu quả để phát hiện và giải quyết ERROR sớm.