Schema 只回答一类问题
OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。因此它适合作为自动生成 reference 和自动验证的事实来源。
问题出现在团队认为“完整 schema = 完整开发者文档”时。
开发者需要一条路径
新用户往往先问：如何认证？使用哪个环境？最小成功请求是什么？资源之间什么关系？如何 retry？这些问题应该由概念性和任务型文档回答，并与 reference 相互链接。
示例承担语义
Schema 可以告诉你一个字段是 string，好示例则告诉你什么值真实、字段如何组合、服务器通常返回什么。尽可能测试示例，并让它们与 API contract 保持足够近，使变更能在 review 时被发现。
把失败当成一等路径
生成的 reference 经常列出错误，却没有说明恢复方式。解释哪些错误可以重试、哪些表示无效状态、rate limit 如何表达，以及支持诊断需要什么 identifier。
不要创造实现没有保证的承诺。不明确的 retry 或 idempotency 是产品问题，不是写作者应该凭空补齐的文字。
让 OpenAPI 做最擅长的事
用 specification 消除字段级事实重复、生成结构并验证示例。把人工编辑精力放在心智模型、workflow、trade-off 和恢复上。
优秀的 API 文档把 schema 当作证据，把发布的网站当作围绕证据设计的开发者体验。
实践示例
把《OpenAPI 是事实来源，但不是完整的 API 文档》变成一个完整的开发者任务。选择一个虚构但真实的资源，例如报告、设备或订单，描述从认证到成功结果的最短路径。包括请求、关键响应字段、一个常见失败以及失败后的下一步。
像真正要根据示例开发客户端一样检查：
- 开发者必须替换哪些值；
- 服务器返回哪些标识符，后续在哪里继续使用；
- 哪个状态或字段表示成功；
- 凭证、输入或限流失败时应该采取什么动作。
API 文档的目标不是让开发者只认识 endpoint 名称，而是让他们能够预测系统交互。
快速编辑检查
- Schema 只回答一类问题. OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。
- 开发者需要一条路径. 新用户往往先问：如何认证？使用哪个环境？最小成功请求是什么？
- 示例承担语义. Schema 可以告诉你一个字段是 string，好示例则告诉你什么值真实、字段如何组合、服务器通常返回什么。
- 把失败当成一等路径. 生成的 reference 经常列出错误，却没有说明恢复方式。
