跳到主要内容
版本：Latest(v3.0) 🔥

API Docs Validator

📋 API Document Validation​

概述​

Path: 左侧边栏 → API Document Validation

Menu Type: 组菜单（包括子菜单）

API 文档验证功能提供了验证 API 规范的格式和结构以及监控验证状态的功能。

How to Access​

  1. 点击左侧边栏中的 API Document Validation 菜单以展开其子菜单。
  2. 从展开的子菜单列表中选择所需的功能。

💡 注意：由于 API 文档验证是一个组菜单，点击它会切换子菜单的展开和折叠。

当用户点击 API 文档验证菜单时，将显示以下子菜单：

  1. API Document Settings – 配置 API 验证规则
  2. API Document Status Dashboard – 查看和监控验证状态

API Document Settings {#api document settinPathML_10__: Left Sidebar > API Document Validation > API Document Settings ​

Feature Overview​

API 文档设置页面允许用户定义、管理和应用 API 文档验证器的验证规则集。它通过允许用户创建可自定义的规则集、配置验证功能并将其映射到特定项目，支持标准化的 API 文档质量。

页面结构​

Main Section
  1. API Docs Validator Setting
    • 规则集管理
    • 项目映射
  2. Validation Ruleset Management
    • 查看和管理现有规则集列表
  • Add New Ruleset 按钮
  1. Project Selection
    • 使用项目下拉菜单选择特定项目

关键特性​

  • Validation Ruleset Management: 创建、编辑和删除验证规则集
  • Add New Ruleset: 使用预定义模板创建新规则集，并通过添加或删除功能自定义验证功能
  • Project Mapping: 将验证规则集与特定项目关联
  • Default Rulesets
    • OWASP Top10: 基于 OWASP 前 10 大安全漏洞的验证规则
    • OAS(2.X, 3.X): OpenAPI 规范的验证规则

如何使用​

  1. 点击左侧边栏中的 API Document Validation 菜单以展开子菜单
  2. 在子菜单中选择 API Document Settings
  3. 从 Project 下拉菜单中选择一个项目（可选）
  4. 在 Validation Ruleset Management 部分查看或管理现有规则集
  5. 点击 Add New Ruleset 创建新的验证规则集
    • 点击 Add New Ruleset 时，会出现一个模态对话框，包含三个模板：
      • Default Rule
      • Basic Rule
      • Advanced Rule
    • 输入规则集信息：输入规则集名称、描述
    • 选择一个模板并自定义其验证功能：
      • 打开 Functions List 查看模板中包含的所有验证功能
      • 通过从编辑器中删除现有功能来移除功能，并点击功能以从可用功能列表中添加新功能
      • 将鼠标悬停在功能名称上以查看简短描述
      • 点击功能列表下方的链接在新标签页中打开
  6. 点击按钮 Save 将新项目添加到规则集管理列表中。

规则集类型​

  • OWASP Top10: 验证前 10 大网络应用程序安全漏洞
  • OAS(2.X, 3.X): Validates OpenAPI Specification versions 2.x and 3.x

Cautions​

  • ⚠️ 规则集的更改必须保存才能生效
  • ⚠️ 当验证规则仅适用于特定项目时，应使用项目映射

API Document Status Dashboard {#api-document-status-dashboPathTML_3__: Left Sidebar > API Document Validation > API Document Status Dashboard }​

功能描述​

API 文档状态仪表板允许用户查看和监控 API 格式验证执行历史和结果。

页面结构​

Validation History Table

以表格格式显示验证执行历史。

列名描述
请求者请求验证的用户
项目名称目标项目
API 名称目标 API
状态验证状态（通过 / 失败等）
错误计数检测到的错误数量
错误原因验证失败的原因
验证时间执行的日期和时间
操作查看详细信息，重新运行验证等

关键功能​

  • View Validation History: 回顾过去的验证执行
  • Monitor Validation Status: 检查通过/失败结果
  • Error Analysis: 回顾错误计数和原因
  • Filtering: 使用项目下拉菜单按项目过滤（可选）

如何使用​

  1. 点击左侧边栏中的 API Document Validation 菜单以展开子菜单
  2. 在子菜单中选择 API Document Settings
  3. 在 Validation History 表中检查验证执行历史。
  4. 使用 Project 下拉菜单选择特定项目进行过滤（可选）。
  5. 使用表格的 Actions 列查看详细信息或执行其他操作

Table Functions​

  • Pagination: 当历史记录较大时，逐页查看结果
  • Sorting: 通过点击列标题进行排序（如果支持）
  • Detail View: 通过操作列查看详细信息

Usage tips​

  • 💡 Project Filtering: 使用项目下拉菜单查看特定项目的验证历史
  • 💡 Status Check: 通过状态列快速识别通过/失败结果
  • 💡 Error Analysis: 使用 Error Count 和 Error Cause 列识别验证问题
  • 💡 Latest Data: 刷新页面以查看最新的验证结果

Swagger 文档格式验证 {#swagger-document-format-validatiPathML_12__: Left Sidebar > API Document Validation > API Document Validation ​

功能概述​

Swagger 文档格式验证允许用户输入 Swagger/OpenAPI 定义并根据配置的规则进行验证。这有助于在部署之前识别 Swagger 文档中的标准合规性问题和错误。

页面结构​

1. Project Configuration Section
  • Project Selection: 选择要验证的项目
    • 例如，otel-prj
  • 根据所选项目自动加载应用的验证规则
2. Applied Validation Rules Section

显示应用于所选项目的规则集和规则：

  • Ruleset Name: 应用规则集的名称（例如，MCP Swagger）
  • Applied Rules Examples:
    • mcp-operation-id-required: 需要进行 operationId 验证
    • mcp-operation-id-style: operationId 样式验证
  • mcp-operation-summary-required: 操作摘要验证是必需的
    • mcp-json-request-body: JSON 请求体验证
    • mcp-json-request-body-schema: JSON 请求体架构验证
    • 其他规则
  • Rule count: 显示总规则数量（例如，“以及 N 条附加规则”）
3. Swagger JSON Input Section
  • Input Field: 一个大型文本区域，用户可以在其中输入 Swagger/OpenAPI JSON 定义。
    • 默认指导消息：“请输入 Swagger JSON”
    • 支持 OpenAPI 3.0 格式的 Swagger 定义
  • Load Sample Button: 一个位于输入字段右上角的蓝色按钮。
    • 自动加载示例 Swagger 定义（例如，Petstore 示例）到输入字段
    • 允许用户查看输入格式并进行测试验证
  • Validation Status Indicators: 在输入字段下方显示 JSON 验证结果。
    • 有效 JSON：当 JSON 格式有效时，显示绿色勾选图标
    • OpenAPI 规范：当定义符合 OpenAPI 规范时，显示绿色勾选图标
  • Run Swagger Validation Button: 一个位于页面底部中央的大蓝色按钮。
    • 针对输入的 Swagger JSON 执行所有配置的验证规则
    • 点击后立即开始验证，结果显示在下方
  • Export Results Button: 一个位于验证运行按钮旁边的绿色按钮
    • 允许用户将验证结果导出到文件
4. Validation Results Section

验证执行后，结果显示在页面底部。

Summary Information (顶部卡片格式):

  • ERROR: 检测到的错误数量，显示在红色背景上
    • 例如，1 个错误
  • WARNING: 检测到的警告数量，显示在橙色背景上
    • 例如，0 个警告
  • SUCCESS: 成功验证的数量，显示在绿色背景上
    • 例如，8 次成功
  • FAIL - Total N Issues: 验证问题的总数，显示为红色标签
    • 例如，失败 - 总共 1 个问题
Detailed Results Table:
列名描述
严重性显示错误（红色）或成功（绿色）
规则应用的验证规则名称（例如，mcp-json-request-body）
消息验证结果消息（例如，“content”属性必须有...）
路径Swagger 定义中发生错误的路径
规则集名称规则所属的规则集名称
操作通过点击“View Detail”按钮查看每个项目的详细信息
Table function:
  • Pagination: 在存在大量验证结果时逐页显示结果（例如，“每页行数：10”）
  • Sorting: 通过点击列标题对结果进行排序
  • Detail View: 点击 View Details 按钮在 Action 列中查看每个验证项目的详细信息

关键特性​

1. Apply Project-specific validation rules
  • 选择项目时，映射到该项目的验证规则会自动应用。
  • 每个项目可以应用不同的验证规则。
2. Swagger JSON input and validation
  • 开发的 API 的 Swagger/OpenAPI 定义可以直接输入进行验证。
  • 实时检查 JSON 格式的有效性和 OpenAPI 规范的合规性。
3. Sample load function
  • 点击 Sample Load 按钮自动输入示例 Swagger 定义。
  • 该示例可用于检查所需的输入格式并测试功能。
4. Run validation and view results
  • 点击 Run Swagger Validation 按钮运行所有配置的验证规则。
  • 验证结果分为错误、警告或通过。
  • 每个验证项（规则、消息、路径）的详细信息可以查看。
5. Export results
  • 验证结果可以导出为文件以供文档或共享使用。

如何使用​

Basic Validation Process
  1. Select Project: 从顶部的 project to be validated 下拉菜单中，选择要验证的项目。
  2. Check Validation Rules: 检查 Applied Validation Rules 部分的规则列表。
  3. Enter Swagger JSON:
    • Method 1: 复制已开发 API 的 Swagger JSON，并将其粘贴到输入字段中。
    • Method 2: 点击 Load Sample 按钮以加载示例 Swagger 并进行修改。
  4. Check JSON Validity: 在输入字段的底部，检查有效 JSON 和 OpenAPI 规范的指示器。
  5. Run Validation: 点击 Run Swagger Validation 按钮。
  6. Review Results: 在底部的 Validation Results 部分，检查摘要信息和详细结果。
  7. Fix Errors: 如果发现错误，请参考消息和路径信息以纠正 Swagger 定义。
  8. Re-validate: 纠正后，再次运行验证以确认所有错误已解决。

Practical Usage Scenarios ​

Scenario 1: Swagger Validation After Development Completion
  1. 完成 API 开发后，生成 Swagger/OpenAPI 定义。
  2. 从左侧边栏导航到 API Management > API Format Validation。
  3. 在 project to be validated 部分选择要验证的项目。
  4. 复制生成的 Swagger JSON，并将其粘贴到输入字段中。
  5. 点击 Run Swagger Validation 按钮。
  6. 查看结果并修复任何错误。
  7. 重复直到所有验证通过。
Scenario 2: Validation Test Using Sample 
  1. 选择 project to be validated。
  2. 点击 Load Sample 按钮以加载示例 Swagger。
  3. 使用示例 Swagger 作为参考来编写实际的 Swagger 定义。
  4. 点击 Run Swagger Validation 按钮进行验证。
  5. 审查结果并进行必要的更正。

Scenario 3: Validation Rule Compliance Check  

  1. 选择项目以检查应用的验证规则。
  2. 输入 Swagger JSON。
  3. 运行验证。
  4. 在  Detailed results table 中，检查每个规则的验证结果。
  5. 审查带有 ERROR 和 WARNING 的规则并修复它们。
  6. 点击 View Details 按钮以查看有关错误的更多信息。

使用示例​

Example 1: Basic Validation Execution 

  1. 选择 otel-prj 项目
  2. 点击 Load Sample 以加载示例 Swagger
  3. 点击 Run Swagger Validation
  4. 检查验证结果：
    • 错误：1
    • 警告：0
    • 通过：8

Example 2: Actual Swagger Validation 

  1. 复制已完成 API 的 Swagger JSON
  2. 选择项目（例如， otel-prj）
  3. 将 Swagger JSON 粘贴到输入字段中
  4. 检查 JSON 有效性（检查有效 JSON，OpenAPI 规范）
  5. 点击按钮 Run Swagger Validation 
  6. 审查验证结果中的错误：
    • 示例：违反 mcp-json-request-body 规则
    • 消息："content" 属性必须具有必需的属性 "application/json"
    • 路径：paths./pet/{petId}/uploadImage.post.requestBody.content
  7. 修复 Swagger 定义中此路径的错误
  8. 修复后重新运行验证
  9. 确认所有验证通过

Example 3: Validation Result Analysis 

  1. 运行验证后，检查 Validation Results 部分 
  2. 检查 summary information 中的问题总数（例如，FAIL - 总共 1 个问题）
  3. 在 Detailed results table 中，检查每个项目： 
    • Severity：检查优先处理带有 ERROR 的项目
    • Rule：检查哪个规则失败
  • Message: 检查具体错误详情
    • Path: 检查Swagger定义中需要修复的确切位置
  1. 点击 View Details 获取更多信息
  2. 修复错误并重新运行验证

Cautions​

  • ⚠️ Project Selection Required: 由于验证规则可能因项目而异，必须选择正确的项目。
  • ⚠️ JSON Format Compliance: 输入的Swagger必须是有效的JSON格式，并且必须符合OpenAPI规范。
  • ⚠️ Validation Rule Review: 请提前检查应用于项目的验证规则，并准备Swagger，以确保所有必需项都得到正确遵循。
  • ⚠️ Re-validation After Fixing: 修复错误后，请确保再次运行验证，以确认所有问题已解决。
  • ⚠️ Save Validation Results: 使用 result 导出功能保存重要的验证结果。

使用提示​

  • 💡 Use Samples: 对于首次使用，请使用 load sample 按钮检查所需的输入格式。
  • 💡 Real-time Validation: 在输入JSON时，请检查有效JSON和OpenAPI规范指示器以进行实时验证。
  • 💡 Rule-based Filtering: 验证结果表可以按规则过滤，以仅查看特定验证规则的结果。
  • 💡 Path Utilization: 验证结果中的路径信息可用于定位Swagger定义中的确切位置并进行修正。
  • 💡 Repeated validation: 在开发过程中定期运行验证对于及早发现和解决错误是有效的。