零基础也能懂的 API 接口文档编写指南，适合开发人员

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 文档编写指南。好的文档是一个持续改进的过程，要根据用户反馈不断优化和更新。如果你在使用过程中有任何疑问，都可以继续提出。