如何验证 API 定义的相关信息？
API 定义在实践中的含义
API 定义通常指 API 工作方式的正式规范：可用的端点（或操作）、必需输入、可选输入、预期输出、数据类型、验证规则以及错误格式。它可以体现为 OpenAPI/Swagger 文档、JSON schema、内部开发者规范，或人类可读的文档。
当你验证 API 定义的信息时，你并不是在确认某个概念是否“普遍为真”——而是在检查所记录的契约对于给定的 API 版本是否一致、可测试且可复现。
验证过程如何运作（来源层级）
使用与“稳定机制”确认方式相匹配的来源层级。
-
主要契约工件（最稳定）
- 提供商发布的实际 API 定义文档（例如 OpenAPI 文件）。
- 随文档附带的任何机器可读 schema。
- 记录的版本标识符和变更日志。
-
提供商文档（解释层）
- 描述如何构造请求和解释响应的指南。
- 错误处理和身份验证/授权部分（如果它们影响请求/响应结构）。
-
受控测试中的观察行为（现实检查）
- 在非生产环境或沙箱环境中执行的一组小规模请求（如可用）。
- 验证响应字段、类型和约束是否与定义一致。
在实践中，当你能证明文档、schema 和响应在相同版本下一致时，验证最为有力。
证据与可复现的验证步骤
遵循可重复的逐步流程。
步骤 1：锁定版本和范围
记录下你所使用的 API 版本以及确切的定义工件（文件名、URL 或提交标识符）。假设不同版本可能具有不同的字段名、必需参数和错误格式。
步骤 2：对照定义交叉检查结构
针对你关心的每个端点，验证以下内容：
- 必需参数列表是否明确。
- 可选参数是否可区分。
- 输出字段是否附带数据类型或 schema 进行了文档化。
- 错误响应是否具有已记录的结构（例如，错误代码加消息，或验证问题列表）。
步骤 3：创建带有明确假设的最小测试用例
选择一组小的请求，覆盖以下情况：
- 仅包含必需字段的“正常路径”情况。
- 验证用例（故意使用错误类型或缺失必需字段），以确认错误行为。
假设无实时市场数据。如果 API 需要通常依赖外部状态的参数（如交易品种或标识符），请使用测试环境提供的值，或将缺失/无效值视为测试输入，而非尝试预测结果。
步骤 4：将响应与定义进行比较
针对每个响应：
- 检查响应负载是否包含所描述的字段。
- 检查数据类型是否符合预期（字符串 vs 数字，对象 vs 列表）。
- 确认当请求无效时，错误是否按文档所述的格式呈现。
如果定义中说明某字段为可选，但在响应中从未出现，则应记录为差异。相反，如果某些额外字段持续出现，请将其记录为“观察到但未文档化”，这可能表明文档存在空白。
步骤 5：追踪故障模式，而不仅仅是结果
至少应将一个实质性限制纳入验证范围：
- 版本漂移：文档可能在更新后滞后于实际行为。
- 不一致的 schema：字段可能被文档化但缺失或重命名。
- 验证差异：错误格式可能在不同端点间变化。
- 环境差异：沙箱与生产环境的行为可能不一致。
将这些视为验证结果，而非正确性的信号。
预期的限制与风险
即使经过仔细检查，验证仍受限于不确定性和变更。
- 单次测试无法保证长期准确性。定义今天正确，仍可能在提供商更新后过时。
- 行为可能因上下文而异。成本、执行条件、权限和网络故障可能改变你看到的响应，即使契约稳定。
- 历史一致性不保证未来一致性。如果之前响应匹配，并不意味着版本变更后仍会匹配。
鉴于这些限制，应将验证与特定版本和特定测试环境绑定。
验证清单与待解决的下一个问题
使用此清单使你的验证可复现：
- 已记录文档和测试的版本。
- 已从定义中列举出端点和字段。
- 已创建带有明确假设的最小“正常路径”和“验证失败”请求。