你的 API 文档列出了 47 个端点。每个端点都标注了 HTTP 方法、路径、请求体和响应模式。它完整、准确，但毫无用处。
为什么？因为当我打开你的文档时，我通常不想要一份端点清单。
我想要完成一个任务。
我想知道如何创建客户、绑定支付方式、启动订阅、处理 webhook、从失败中恢复，以及安全地进行测试。
端点参考是必要的。但它不是产品本身。
参考不是上手引导
参考页面回答的是：
- 存在什么路径
- 它接受什么方法
- 允许哪些字段
- 响应长什么样
上手引导回答的是：
- 我应该先做什么？
- 这些调用的顺序是什么？
- 什么会失败？
- 我应该存储什么？
- 如何在不破坏生产环境的情况下测试？
如果你的文档只有参考页面，开发者就必须从原始零件中逆向推导出工作流程。
这就是为什么"完整"的文档仍然让人感觉无法使用。
从开发者实际的任务开始
对于大多数 API，真正的文档应该从任务路径开始：
- 认证请求
- 创建第一个资源
- 安全地更新资源
- 监听 webhook
- 重试失败的操作
- 从测试模式切换到生产模式
然后每个任务可以链接到端点参考。
指南从开发者的目标开始，展示一条可行的路径，包含示例，然后链接到具体的端点细节。
顺序很重要。如果第一页是一个巨大的参考表格，你就是在要求读者独自构建心智模型。
展示完整路径，而非孤立调用
糟糕的文档只展示一个完美的请求：
POST /customers更好的文档展示序列：
- 创建客户。
- 创建订阅。
- 存储返回的 ID。
- 监听确认 webhook。
- 处理失败和取消状态。
这个序列才是开发者完成集成所需要的。
更好的是，包含状态机的形态：
错误文档是集成的一部分
一个严肃的 API 会告诉开发者在失败时该怎么做。
不要止步于：
{ "error": "invalid_request" }要记录：
- 该请求是否可以安全重试
- 操作是否可能部分成功
- 哪些错误需要用户操作
- 哪些错误需要运维人员操作
- 发送给支持团队时需要提供什么 ID
- webhook 是否具有权威性
这就是 API 文档成为信任基础设施的地方。
使用符合生产实际的示例
如果生产工作流不是玩具，示例也不应该是玩具。
糟糕：
{ "name": "John" }更好：
{
"externalId": "acct_123",
"email": "operator@example.com",
"plan": "studio-audit",
"metadata": {
"source": "route-finder",
"campaign": "content-engine"
}
}更好的示例教会了命名、元数据、幂等性和归因。它帮助开发者构建真实的东西。
在上线前添加清单
每个具有真实业务影响的 API 都应该包含一个上线清单。
这个清单不能替代参考文档。它让参考文档变得可用。
让文档可测试
最好的 API 文档与系统足够接近，以至于当系统发生变化时它们会失效。
这意味着：
- 示例从类型化模式生成
- 请求示例在 CI 中验证
- OpenAPI 输出与路由处理器对照检查
- 每次构建都检查文档链接
- 对公共工作流进行契约测试
如果文档远离代码、手动维护，它们就会漂移。一旦漂移，开发者就不再信任它们。
我喜欢的结构
对于一个严肃的 API，我会采用这样的信息架构：
- 从这里开始：API 的功能以及你能构建什么。
- 快速入门：一条完整的快乐路径。
- 认证：密钥、作用域、轮换、本地设置。
- 核心工作流：基于任务的指南。
- Webhooks/事件：投递、重试、签名、重放。
- 错误/重试：什么失败了以及该怎么做。
- 参考：端点级别的细节。
- 生产清单：上线护栏。
- 变更日志：破坏性变更和迁移说明。
这并不过分。这正是让开发者无需销售工程师陪同就能完成集成的关键。
