原创

API 文档怎么写

很多产品做了 API，但文档只是一张参数表。接口地址、请求方法、字段类型、返回示例，看起来都有，却很难让开发者真正用起来。开发者打开文档后，仍然不知道从哪里开始，怎么拿 token，第一段代码怎么写，失败了怎么排查。

好的 API 文档不是“把接口列出来”，而是帮助开发者尽快完成第一次成功调用。第一次成功调用越快，开发者越容易继续集成；第一次卡住越久，流失越快。

对早期产品来说，API 文档不需要像大平台一样庞大，但必须清楚、可复制、可验证、能排错。

先写 Quickstart

API 文档最重要的部分不是完整接口列表，而是 Quickstart。开发者第一次打开文档，应该能在几分钟内完成一个最小调用。

Quickstart 至少包含：创建 API Key、安装或准备请求工具、发起第一个请求、看到成功返回、理解下一步。不要一开始就让开发者阅读概念、权限模型和所有参数。

一个好的 Quickstart 应该像这样：

1. 获取 API Key
2. 复制 curl 示例
3. 替换 token
4. 发送请求
5. 得到一个真实返回
6. 根据返回 ID 查询结果

如果你的 API 需要异步任务，就不要只写创建任务接口，还要写如何查询状态、如何获取结果、失败时怎么处理。开发者关心的是完整闭环，不是单个接口。

每个接口都要说明使用场景

很多 API 文档的问题，是只写接口本身，不写什么时候用。开发者看到 POST /tasks，知道它创建任务，但不知道这个接口适合什么场景、和其他接口是什么关系、调用后下一步是什么。

每个接口前面都应该有一句话说明使用场景。比如：“当你需要为一个 URL 生成竞品分析报告时，调用这个接口创建分析任务。”这比单纯写“创建任务”有用得多。

接口文档应该包含：接口目的、请求方法、路径、认证方式、请求参数、返回字段、成功示例、失败示例、常见错误、下一步接口。

尤其是“下一步接口”很重要。创建资源之后是查询详情？上传文件之后是等待处理？支付回调之后是更新订单？文档要引导开发者继续走。

示例代码必须可以复制运行

API 文档里的示例代码，不能只是伪代码。它应该可以复制、替换 token 后直接运行。

最基础的示例是 curl。因为它不依赖语言环境，开发者可以快速验证接口是否可用。除此之外，可以根据目标用户提供 JavaScript、Python、PHP、Go 等示例。

示例代码要包含完整请求头、认证方式、请求体和返回结果。不要省略关键字段，也不要用和实际 API 不一致的字段名。

坏示例是：

调用接口并传入参数即可。

好示例是：

curl -X POST https://api.example.com/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","language":"zh"}'

开发者最喜欢的是能跑通的代码，而不是长篇解释。

错误码要写清楚怎么处理

API 调用一定会失败。认证失败、参数错误、额度不足、资源不存在、频率限制、服务超时、任务失败，都会发生。

文档不能只列错误码，还要写处理建议。比如 401 是 API Key 无效，检查 token 是否正确；429 是请求过多，建议退避重试；402 是额度不足，引导用户升级或充值；500 是服务异常，可以稍后重试或联系支持。

错误返回格式也要统一。不要有的接口返回 message，有的返回 error，有的返回字符串。统一格式能让开发者更容易写错误处理。

一个推荐格式是：

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry later.",
    "request_id": "req_123"
  }
}

request_id 很重要。开发者反馈问题时，你可以通过它查日志。

认证和权限要单独讲清楚

API 文档必须明确认证方式。是 Bearer Token、Basic Auth、签名、OAuth，还是 webhook secret？API Key 在哪里创建？是否可以轮换？泄露后如何撤销？不同权限的 Key 能访问哪些资源？

很多开发者第一次集成卡在认证。文档里应该有一个独立的 Authentication 页面，包含请求头写法、Key 管理、权限范围、安全建议和常见错误。

如果你的 API 有沙箱和生产环境，也要写清楚 base URL 的区别。不要让开发者拿测试 key 调生产接口，或拿生产 key 在本地乱试。

API Key 是安全边界，不只是一个字符串。文档要提醒开发者不要把 Key 暴露在前端代码、移动端包或公开仓库里。

Webhook 文档要更具体

如果产品支持 Webhook，文档要写得比普通接口更具体。因为 Webhook 是你的系统主动调用开发者的系统，排错更难。

Webhook 文档至少包含：事件类型、请求方式、事件 payload、签名验证、重试策略、超时时间、幂等处理、测试方法。

尤其要讲签名验证和幂等。开发者需要知道如何确认请求来自你，而不是伪造请求；也要知道同一个事件可能被发送多次，不能重复扣费、重复发货或重复创建记录。

Webhook 示例最好提供完整 payload，而不是只写字段表。开发者需要看到真实事件长什么样。

一个 API 文档结构模板

你可以用下面结构组织第一版 API 文档：

Overview
- API 能做什么
- Base URL
- 版本说明

Quickstart
- 获取 API Key
- 第一次调用
- 查询结果

Authentication
- 请求头格式
- Key 管理
- 权限范围

Core APIs
- 创建资源
- 查询状态
- 获取结果
- 更新 / 删除

Errors
- 错误格式
- 常见错误码
- 处理建议

Webhooks
- 事件列表
- 签名验证
- 重试和幂等

SDK / Examples
- curl
- JavaScript
- Python

第一版不一定要有 SDK，但至少要有 curl 和一种主流语言示例。只要开发者能快速跑通，文档就已经比很多参数表强。