API 文档就像是一本使用说明书，它告诉其他开发者如何使用你提供的服务。
举个简单的例子：
如果 API 是一台咖啡机，那 API 文档就是咖啡机的使用说明书
如果 API 是一个积木玩具，那 API 文档就是积木的组装说明
为什么需要编写 API 文档？
好的 API 文档能带来以下好处：
减少学习成本：新用户可以快速上手
降低沟通成本：减少反复解答相同的问题
提高开发效率：清晰的说明可以避免错误使用
减少维护压力：用户可以自助解决问题
好的 API 文档具备哪些特征？
👍 清晰易懂：像跟朋友聊天一样自然
👍 结构合理：像图书馆的书架一样有序
👍 示例丰富：像烹饪菜谱一样详细
👍 持续更新：像新闻一样保持时效性
写 API 文档开始之前的准备工作
1. 了解你的读者
不同类型的读者需要不同的信息：
读者类型
需求重点
举例
初级开发者
基础概念和详细步骤
如何获取 API 密钥，如何发送第一个请求
高级开发者
技术细节和高级特性
性能优化，错误处理机制
项目经理
功能概述和业务价值
API 能解决什么问题，如何集成
2. 确定文档内容清单
必须包含的基本信息：
📝 API 基础信息
API 服务器地址
支持的协议（如 HTTP/HTTPS）
API 版本信息
🔐 认证信息
认证方式（如 API 密钥、OAuth2.0）
获取和配置方法
📚 接口信息
所有可用的 API 列表
每个接口的详细说明
请求和响应示例
3. 选择合适的 API 文档工具
常用工具推荐：
Swagger/OpenAPI：自动生成交互式文档
GitBook：适合编写详细的说明文档
Markdown：轻量级标记语言，适合编写基础文档
Apifox：接口测试和文档生成，可通过 IDEA 插件一键生成 API 文档
你可以通过以上的任一工具来辅助撰写 API 文档，笔者比较常用的是 Apifox，它支持 Markdown 编写，并且 .md 文件与 API 接口可以共存，可以通过 IDEA 插件或者 Swagger/OpenAPI 文档快速导入。API 文档可以分享出去，分享出去的文档如果有接口，也可以进行在线调式，还是很方便的。
API 文档结构示例
注：以下截图均为 Apifox 的公开线上文档示例，仅做参考。
1. 文档概述部分
文档概述是 API 文档的"第一印象"，它就像一本书的封面和目录。这部分内容帮助用户快速了解：
这个 API 是做什么用的
API 的当前版本和更新状态
使用这个 API 需要知道的基本信息
例如：
# 天气查询API文档
版本：v1.0
最后更新：2024-01-20
## 简介
本API提供全球主要城市的天气查询服务，支持实时天气和未来7天预报查询。
## 基础信息
- 服务地址：https://api.weather.example.com
- 协议：HTTPS
- 数据格式：JSON
- 编码：UTF-8
2. 认证说明部分
认证部分相当于 API 的"门禁系统"。这部分内容必不可少，因为它可以帮助用户理解如何获得访问权限，保证 API 的安全性，防止恶意调用和滥用。
例如：
## 认证方式
所有API请求都需要在请求头中包含API密钥：
请求头格式：
X-API-Key: your_api_key_here
获取API密钥的步骤：
1. 注册账号：https://weather.example.com/register
2. 登录控制台：https://weather.example.com/console
3. 创建API密钥
3. 接口说明示例
接口说明是 API 文档的核心内容。它详细说明：
如何构造请求
需要提供什么参数
参数的具体要求
没有详细的接口说明，用户就无法正确调用 API。例如：
## 获取实时天气
获取指定城市的实时天气信息。
### 请求信息
- 方法：GET
- 路径：/v1/weather/current
- 完整URL：https://api.weather.example.com/v1/weather/current
### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|-------|------|------|------|
| city | string | 是 | 城市名称，如"Tokyo" |
| lang | string | 否 | 返回语言，默认"en_US" |
### 请求示例
```curl
curl -X GET "https://api.weather.example.com/v1/weather/current?city=Tokyo" \
-H "X-API-Key: your_api_key_here"
```
4. 响应示例
响应示例就像是预期的"成品展示"。它的重要性在于：
让用户知道会得到什么数据
帮助用户提前规划数据处理逻辑
减少试错成本
例如：
{
"code": 200,
"data": {
"city": "Tokyo",
"temperature": 20,
"humidity": 65,
"weather": "Sunny",
"updated_at": "2024-01-20T10:00:00Z"
}
}
5. 错误码说明
可以帮助用户快速定位问题，提供清晰的解决方案。
错误码
说明
处理方法
400
请求参数错误
检查参数是否正确
401
未授权
检查 API 密钥是否有效
404
城市未找到
确认城市名称是否正确
实用的代码示例
需要在 API 文档中增加一些常见编程语言的示例代码，帮助用户理解 API 怎么调用。
1. Python 示例
import requests
def get_weather(city):
api_key = 'your_api_key_here'
url = 'https://api.weather.example.com/v1/weather/current'
headers = {
'X-API-Key': api_key
}
params = {
'city': city
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
data = response.json()
return data['data']
else:
return f"错误: {response.status_code}"
# 使用示例
weather = get_weather('Tokyo')
print(f"当前温度: {weather['temperature']}°C")
2. JavaScript 示例
async function getWeather(city) {
const API_KEY = 'your_api_key_here';
const url = `https://api.weather.example.com/v1/weather/current?city=${city}`;
try {
const response = await fetch(url, {
headers: {
'X-API-Key': API_KEY
}
});
const data = await response.json();
return data.data;
} catch (error) {
console.error('获取天气信息失败:', error);
}
}
// 使用示例
getWeather('Tokyo')
.then(weather => console.log(`当前温度: ${weather.temperature}°C`));
常见问题（FAQ）
在 API 文档中添加常见问题，可以极大减少技术支持成本。
1. API 调用问题
Q: 为什么我的 API 请求返回 401 错误？
A: 通常是因为：
API 密钥未正确设置在请求头中
API 密钥已过期
API 密钥无效
2. 数据问题
Q: 为什么某些城市查询不到天气？
A: 可能的原因：
城市名称拼写错误
该城市暂不在支持列表中
服务器暂时无法获取该城市的天气数据
最佳实践建议
1. 文档编写建议
✅ 应该做的：
使用简单清晰的语言
提供丰富的代码示例
及时更新文档内容
保持格式统一
❌ 不应该做的：
使用晦涩难懂的术语
省略错误处理说明
忽略示例代码
随意改变文档结构
2. API 使用建议
正确处理所有可能的错误情况
合理控制请求频率
定期检查 API 密钥有效性
做好日志记录
扩展资源
1. 推荐工具
工具名称
用途
特点
Swagger
API 文档生成
自动化、交互性强
GitBook
文档托管
版本控制、协作便捷
Apifox
API 测试、API 文档工具
版本控制，协作便捷，便于调试、分享，可通过通过 IDEA 插件一键生成 API 文档
2. 学习资源
Swagger 文档
Apifox 文档
总结
1. 文档编写要点
以用户为中心
保持简单明了
示例要具体
持续更新维护
2. 检查清单
基本信息完整
认证方式清晰
示例代码充分
错误处理完整
格式统一规范
以上就是一个完整的 API 文档编写指南。好的文档是一个持续改进的过程，要根据用户反馈不断优化和更新。如果你在使用过程中有任何疑问，都可以继续提出。