从契约开始
REST API 文档同时面向机器和人。机器可读契约描述 path、method、parameter、schema 与 response；人类文档解释意图、约束、工作流和开发者要做的选择。两层都需要。
让成功路径可以直接运行
展示认证、完整 request 与完整 response，让开发者尽快完成第一次成功调用。示例必须有效且真实。
错误也是接口的一部分
不要只写 200。记录认证失败、验证错误、冲突、限流和异步状态，并说明调用方下一步能做什么。
分离 reference 与 guides
Reference 回答“有什么”，guide 回答“怎样完成目标”。不要把架构、onboarding 和 troubleshooting 全塞进一个 endpoint 页面。
保证示例可执行
示例比正文更容易过期。尽可能在 CI 中验证 JSON、schema 和典型请求。
OpenAPI 是来源，不是全部体验
OpenAPI 很适合生成 reference 和做验证，但 schema 无法独立解释业务意图。补充概念、认证、生命周期、限制和端到端场景。
实践示例
把《如何正确编写 REST API 文档》变成一个完整的开发者任务。选择一个虚构但真实的资源，例如报告、设备或订单，描述从认证到成功结果的最短路径。包括请求、关键响应字段、一个常见失败以及失败后的下一步。
像真正要根据示例开发客户端一样检查：
- 开发者必须替换哪些值；
- 服务器返回哪些标识符，后续在哪里继续使用；
- 哪个状态或字段表示成功；
- 凭证、输入或限流失败时应该采取什么动作。
API 文档的目标不是让开发者只认识 endpoint 名称，而是让他们能够预测系统交互。
快速编辑检查
- 从契约开始. REST API 文档同时面向机器和人。机器可读契约描述 path、method、parameter、schema 与 response；人类文档解释意图、约束、工作流和开发者要做的选择。
- 让成功路径可以直接运行. 展示认证、完整 request 与完整 response，让开发者尽快完成第一次成功调用。
- 错误也是接口的一部分. 不要只写 200。记录认证失败、验证错误、冲突、限流和异步状态，并说明调用方下一步能做什么。
- 分离 reference 与 guides. Reference 回答“有什么”，guide 回答“怎样完成目标”。
