# V1 支持矩阵

complete 表示 V1 检查完成，不证明完整 OpenAPI 兼容性。分析基于规范声明，无法判断真实服务器行为。

| 结构/变化 | V1 行为 |
| --- | --- |
| OpenAPI 3.0.3 JSON | CLI 每份最大 8 MiB，UTF-8；库 JSON 嵌套限 128 |
| 路径 + HTTP 方法 | 精确匹配；删除每个原有操作各报 1 项 |
| query/header/path/cookie 标量参数 | 按 in + name 匹配；操作级覆盖路径级；同层重复报错 |
| Accept、Content-Type、Authorization header 参数声明 | 按 OpenAPI 3.0.3 忽略这三种保留声明；同名 query 参数仍正常检查 |
| 参数 required 从 false/缺省到 true | 报破坏；新必填参数同样处理 |
| application/json 请求体 | 根 Schema 须显式 object，支持嵌套 object |
| string/integer/number/boolean 属性 | 保留类型，类型变化报告未分析 |
| 对象 required | 新增必填属性报破坏；默认值不抵消必填 |
| 字符串 enum | 值减少、无限制改为有限集合均报破坏；顺序不影响判断 |
| 新可选属性/参数、放宽枚举 | 不报破坏；仍检查新结构是否属于支持范围 |
| 同文档 $ref | 支持对象键、数组下标、~0/~1、UTF-8 百分号片段；缺失目标报错 |
| 共享 Schema/参数/请求体 | 在每个有效使用操作中解析，保留使用和定义位置 |
| 循环、超过 64 层引用/Schema 遍历 | 分析不完整 |
| 反复分叉的共享引用或大量遍历 | 旧/新文档及比较共享 20000 次 Schema/响应遍历额度，超限报告 analysis-work-limit，退出 2；它是工作量限制，不是接口数或文件大小限制 |
| description/summary/title/example/examples/externalDocs/deprecated/x-* | 说明性元数据忽略；同名业务属性不会被删除 |
| info、operationId、tags | 描述/标识元数据，不影响本轮请求规则 |
| minLength/format/nullable 等其他契约字段 | 保留对比；变化报告未分析，不推理兼容性 |
| additionalProperties 布尔值 | 保留；变化报告未分析 |
| 响应契约 | 展开可达引用后检查变化；变化报告未分析，不判断响应兼容方向 |
| 响应 Link 的 parameters 和 requestBody | 保留字面量业务键及值；其中的 description、$ref 等不当成说明字段或文档引用 |
| 鉴权定义、servers、security 等其他契约 | 变化报告未分析 |
| 未被使用的 components Schema/参数 | 不影响被分析操作时忽略，不宣称全规范有效性校验 |
| 新增操作 | 不视为破坏，其中结构仍接受支持范围检查 |
| 删除属性/参数、添加/删除/要求请求体 | 保守报告未分析，人工复核 |

## 不支持的结构

可达请求结构即使两份文档都包含，下列情况也报告不完整：数组、allOf/anyOf/oneOf/not、discriminator、Schema-valued additionalProperties、readOnly/writeOnly 为 true、非字符串枚举、缺少显式 type、非 JSON 媒体类型、参数 content、复杂参数、callbacks、Reference Object 兄弟字段。

YAML 和 3.1 报输入错误；外部引用和非 Pointer 锚点报告不完整。不会为外部引用访问网络。未知字段会得到诊断，已知但本轮不推理的契约变化也会得到诊断。策略偏保守，兼容变化也可能需要人工确认；不提供“忽略不完整继续成功”的选项。

## 定位与稳定性

pointer 是在接口处展开后的逻辑使用位置，引用展开后可能不是原始文件中可直接读取的物理节点；definition_pointer 是该文档实际定义位置。查看引用问题应同时使用两个位置。

问题和诊断按确定性键排序并去重；重复运行及对象属性顺序变化可复现 JSON。排序不承诺自然语言字典顺序，也不含时间戳。

V1 不是完整 OpenAPI 校验器。它验证本轮规则依赖的结构；不能替代规范校验、客户端回归测试或服务端联调。