OpenAPI 请求验证器 - 根据 Schema 检查参数是否正确

OpenAPI Schema 验证是指根据 OpenAPI 规范中定义的 Schema（基于 JSON Schema 标准）来检查 API 请求参数是否符合预期。这包括检查数据类型是否正确（如字符串、数字、布尔值等）、必填字段是否缺失、数值范围是否合规、字符串长度是否超限、枚举值是否在允许范围内、以及正则模式是否匹配等。通过 Schema 验证，可以在请求到达业务逻辑之前拦截不合规的输入，提升 API 的健壮性和安全性。

JSON Schema 主要用于描述请求体（requestBody）的数据结构，支持嵌套对象、数组等复杂类型，使用 type、properties、required、items 等关键字定义结构。

OpenAPI Parameters 则用于描述查询参数（query）、路径参数（path）、请求头（header）等，每个参数有 name、in、required、schema 等属性。本工具支持两种模式，您可以根据实际场景切换使用。

本工具支持以下验证规则：
• 类型检查：string、number、integer、boolean、array、object、null
• 必填检查：required 字段验证
• 枚举检查：enum 值范围验证
• 格式检查：email、date、date-time、uri、url、ipv4、ipv6、hostname
• 数值范围：minimum、maximum、exclusiveMinimum、exclusiveMaximum
• 字符串长度：minLength、maxLength
• 正则匹配：pattern
• 数组验证：minItems、maxItems、items 类型检查
• 嵌套对象：递归验证 properties
• nullable：允许 null 值

常见的验证失败原因包括：
1. 类型不匹配：Schema 要求 integer，但传入了字符串 "123"（注意 JSON 中 123 和 "123" 是不同的）
2. 必填字段缺失：required 数组中列出的字段没有出现在请求数据中
3. 格式不符：如 email 字段没有包含 @ 符号
4. 数值越界：数值小于 minimum 或大于 maximum
5. 枚举越界：值不在 enum 允许的列表中
6. 正则不匹配：字符串不符合 pattern 定义的正则表达式
请仔细对照错误提示中给出的路径和原因进行修正。

本工具支持递归验证嵌套对象。在 Schema 中定义 properties 嵌套结构，工具会自动深入每一层进行检查。例如，如果请求体包含 address 对象，且 address 内部有 city、street 等字段，只需在 Schema 中完整定义这些嵌套属性即可。错误路径会以 $.address.city 的形式明确指出问题所在的层级。

本工具目前要求您将 $ref 引用手动展开为内联 Schema。这是因为 $ref 解析需要完整的文档上下文。建议您使用 Swagger Editor 或其他 OpenAPI 工具先将引用展开，再将完整的 Schema 粘贴到本工具中进行验证。未来版本可能会加入对本地 $ref 的有限支持。

路径使用类似 JSONPath 的表示法：
• $ 表示根对象
• $.name 表示根对象的 name 属性
• $.items[0].title 表示 items 数组第一个元素的 title 属性
• $.address.city 表示嵌套对象 address 中的 city 字段
这种表示法能帮助您快速定位到具体出错的字段。

在 API 开发中使用 Schema 验证有以下好处：
• 提前发现错误：在请求到达业务逻辑之前拦截非法数据
• 减少冗余代码：避免在业务层重复编写参数校验逻辑
• 文档即代码：OpenAPI 规范既是文档也是验证规则，保持一致性
• 提升安全性：防止恶意构造的请求体绕过客户端验证
• 改善开发体验：配合 Swagger UI 等工具自动生成交互式文档