JSON Schema 可视化

Demo：API 文档发布前 review 请求 schema

Schema 图最有价值的地方，是让必填字段、数组对象和组合结构一眼可见。

• 必填字段应该和可选 metadata 明确区分。
• enum 通常会变成 UI 状态或 SDK 常量，需要清楚展示。
• oneOf 和 anyOf 需要文档解释，不应只靠图里的分支。

{
  "type": "object",
  "required": ["email", "plan"],
  "properties": {
    "email": {"type": "string", "format": "email"},
    "plan": {"type": "string", "enum": ["free", "pro"]},
    "metadata": {"type": "object", "additionalProperties": true}
  }
}

这个小 schema 已经包含必填字段、枚举状态和开放 metadata。

Schema Review：在客户端出错前发现破坏性变更

JSON Schema 图特别适合 API 演进评审。它能把 required 字段、enum 变化、嵌套数组、nullable 字段和 oneOf 分支展示得更清楚。

• 新增 required 字段通常是破坏性变更，除非所有客户端已发送。
• enum 新增值要和下游校验规则一起 review。
• oneOf/anyOf 过深时，应把重点分支整理成 review notes。

{
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "status": {"enum": ["draft", "paid", "cancelled"]}
  }
}

文档模式：Schema 树要和示例 payload 配套

Schema 树能解释结构，但开发者仍然需要示例值。建议用可视化树展示必填字段和分支，再在旁边放一个小的请求或响应示例。

• 结构交给树状图，真实取值交给示例 payload。
• 把会映射到 UI 状态或 SDK 常量的 enum 单独说明。
• oneOf/anyOf 过密时，用正文解释每个分支的适用场景。

{
  "email": "user@example.com",
  "plan": "pro",
  "metadata": {"source": "checkout"}
}

示例 payload 能让 Schema 可视化对 SDK 用户和 API 调用方更有用。