通过验证只是起点
从 schema 自动生成的示例可以语法正确却毫无教学价值。string、123、foo 能通过很多 validator，但隐藏了领域意义。好示例应该让读者明白请求为什么存在，以及成功结果能继续做什么。
使用真实感强的值，但不要放入真实 secret 或个人数据。
构造一个小故事
优先展示真实任务序列：创建资源、读取、更新，再处理失败或清理。让 identifier 在步骤之间复用，读者才能看到关系。
在单独的 reference 页里链接到相应 workflow，而不是每个 endpoint 都复制完整 tutorial。
展示真正重要的 response
不要只给 request。展示 status、关键 header 和 body，并指出不明显字段的意义。如果操作是异步的，说明 client 如何知道任务完成。
错误示例同样重要。一个真实的 validation error 往往比另一个 happy path 更能解释 API。
尽可能让示例可执行
可以的话，在 CI 里运行请求或根据 contract 验证 payload。把 sample 存成文件或生成片段，不要手工把同一段代码复制到多页。
优化“可迁移性”
告诉读者应该修改哪些变量，以及哪些前提不能改变。示例的目标是建立可迁移的心智模型。
如果一个示例没有让下一次请求更容易设计，它很可能只是装饰。
实践示例
把《API 示例应该教会流程，而不是装饰 reference》变成一个完整的开发者任务。选择一个虚构但真实的资源，例如报告、设备或订单，描述从认证到成功结果的最短路径。包括请求、关键响应字段、一个常见失败以及失败后的下一步。
像真正要根据示例开发客户端一样检查：
- 开发者必须替换哪些值；
- 服务器返回哪些标识符，后续在哪里继续使用；
- 哪个状态或字段表示成功；
- 凭证、输入或限流失败时应该采取什么动作。
API 文档的目标不是让开发者只认识 endpoint 名称，而是让他们能够预测系统交互。
快速编辑检查
- 通过验证只是起点. 从 schema 自动生成的示例可以语法正确却毫无教学价值。
- 构造一个小故事. 优先展示真实任务序列：创建资源、读取、更新，再处理失败或清理。
- 展示真正重要的 response. 不要只给 request。展示 status、关键 header 和 body，并指出不明显字段的意义。
- 尽可能让示例可执行. 可以的话，在 CI 里运行请求或根据 contract 验证 payload。
