程序员如何做「API 文档」：不是写给机器，是写给人

API 文档是开发者的产品说明书。

好的文档让开发者爱不释手，烂的文档让开发者想骂人。

---

一、API 文档包含什么

1. 接口概览

• 接口地址
• 请求方法
• 功能说明

2. 请求参数

• 参数名
• 参数类型
• 是否必填
• 参数说明
• 示例值

3. 响应参数

• 返回字段
• 字段类型
• 字段说明
• 示例值

4. 错误码

• 错误码
• HTTP 状态码
• 错误信息
• 解决办法

5. 调用示例

• 请求示例
• 响应示例
• 不同场景示例

---

二、好 API 文档的标准

1. 完整

• 所有接口都有文档
• 所有参数都有说明
• 所有错误码都有解释

2. 准确

• 代码示例能跑
• 参数说明正确
• 格式规范一致

3. 清晰

• 结构清晰
• 层次分明
• 一目了然

4. 易找

• 有目录
• 有搜索
• 有索引

---

三、API 文档工具

1. Swagger/OpenAPI

• 自动生成文档
• 可以在线调试
• 支持 API 版本管理

2. YAPI

• 国产，好用
• 支持 Mock
• 支持团队协作

3. Apifox

• 国产新秀
• 一体化（API管理 + 测试 + Mock）

4. 飞书文档

• 简单直接
• 协作方便
• 适合小型团队

---

四、API 设计规范

1. RESTful 规范

• 资源命名：/users、/orders
• HTTP 方法：GET/POST/PUT/DELETE
• 状态码：200/400/404/500

2. 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

3. 统一错误格式

{
  "code": 1001,
  "message": "参数错误",
  "data": null
}

---

五、常见错误

❌ 文档和代码不同步

代码改了，文档没改。

❌ 文档太简陋

只有接口地址，没有参数说明。

❌ 代码示例跑不通

示例代码有错，使用者用了报错。

❌ 没有错误码说明

只说"请求失败"，不说为什么。

---

六、一句话总结

API 文档 = 接口概览 + 请求参数 + 响应参数 + 错误码 + 调用示例，核心是完整 + 准确 + 清晰 + 易找。