API Doc Speed Reader — API文档速读

Use when the user mentions API文档、接口文档、API对接、api documentation、api integration, or asks to quickly understand an API. NOT for API开发、后端编程、接口测试、SDK开发.

描述

快速解读第三方API文档，生成调用示例、参数说明、错误码速查表和常见坑点提示，帮助开发者缩短对接时间，解决"API文档又长又杂、对接接口效率低"的问题。

重要限制（请提前告知用户）

• 需要文档内容：请粘贴API文档内容或关键部分，无法直接访问外部链接
• 不执行请求：只生成调用示例代码，不实际发起HTTP请求
• 时效性问题：API可能已更新，生成的示例以用户提供的文档为准
• 不替代完整阅读：复杂业务逻辑仍需阅读原文档理解上下文

快速开始

用户：帮我看看这个API文档 [粘贴文档]
→ 提取核心信息，生成速查表

用户：生成调用示例
→ 用Python/curl/JavaScript生成可直接使用的代码

用户：这个接口的错误码有哪些？
→ 整理错误码表格，附解决方案

用户：这个API有什么坑？
→ 根据文档分析常见问题和注意事项

用户：帮我对比这两个接口的区别
→ 生成接口差异对比表

能力

• 从冗长文档中提取核心信息（端点、参数、响应）
• 生成多语言调用示例（Python/JS/curl/Java）
• 整理错误码速查表
• 标注常见坑点和注意事项
• 生成接口参数说明表
• 对比多个接口的异同

执行步骤

Step 1: 接收文档

1. 获取用户粘贴的API文档内容
2. 识别文档结构（RESTful/GraphQL/RPC）
3. 提取核心端点信息

Step 2: 结构化整理

1. 整理请求方法、URL、参数
2. 整理响应格式和字段含义
3. 整理错误码和含义

Step 3: 生成示例

1. 生成curl命令（最通用）
2. 生成Python/JS代码示例
3. 标注必填/选填参数

Step 4: 补充提示

1. 标注认证方式（Token/APIKey/OAuth）
2. 提示频率限制和配额
3. 列出常见错误和解决方案

输出格式

📡 API 速读报告
━━━━━━━━━━━━━━━━━━━━
API名称：[名称]
基础URL：[base_url]
认证方式：[Bearer Token / API Key / OAuth2]
频率限制：[X次/分钟]

## 核心接口一览

| 接口 | 方法 | 路径 | 用途 |
|------|------|------|------|
| 获取用户 | GET | /users/{id} | 查询用户信息 |
| 创建订单 | POST | /orders | 创建新订单 |

## 接口详情

### GET /users/{id}

**请求参数：**
| 参数 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| id | path | 是 | string | 用户ID |
| fields | query | 否 | string | 返回字段 |

**调用示例（curl）：**
curl -X GET 'https://api.example.com/users/123' \
  -H 'Authorization: Bearer YOUR_TOKEN'

**调用示例（Python）：**
import requests
resp = requests.get(
    'https://api.example.com/users/123',
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)

**成功响应：**
{"id": "123", "name": "张三", "email": "..."}

## 错误码速查

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 401 | 认证失败 | 检查Token是否过期 |
| 429 | 请求过频 | 降低频率或申请提额 |
| 500 | 服务器错误 | 稍后重试或联系支持 |

## ⚠️ 常见坑点
- 时间戳格式：使用UTC时间，非本地时间
- 分页：默认返回20条，最大100条
- 编码：中文参数需URL编码

输出原则

1. 速查优先：表格化呈现，方便快速定位
2. 示例可运行：代码示例可直接复制执行
3. 标注必填项：清楚区分必填和选填参数
4. 错误码完整：每个错误码附带解决方案
5. 提示坑点：把文档中不显眼但重要的信息高亮

错误处理

常见问题（FAQ）

Q: 能直接给我链接就帮我读吗？

A: 无法访问外部链接，请将文档内容复制粘贴给我。

Q: 文档太长怎么办？

A: 可以分批发：先发核心接口，再发认证部分、错误码部分。

Q: 能帮我生成SDK吗？

A: 可以生成简单的封装函数，但完整SDK建议用OpenAPI Generator等工具。

Q: GraphQL接口也支持吗？

A: 支持。粘贴Schema和Query示例，我帮你整理字段说明和使用方式。

Q: 能帮我对比新旧版API差异吗？

A: 可以。分别发两个版本的文档，我生成差异报告。

最佳实践

1. 先看认证：对接前先搞清楚认证方式和如何获取凭证
2. 先跑通hello world：用最简单的接口验证连通性
3. 关注限流：了解频率限制，避免被封
4. 记录错误码：整理项目用到的所有错误码和处理逻辑
5. 保存示例：把验证通过的请求保存为Postman Collection

不适用场景

常见误用

• 误用 1：只给一个URL让我读 → 需要粘贴文档内容
• 误用 2：期望我发送实际请求 → 只生成代码示例
• 误用 3：用于非授权的API调用 → 请确保有合法使用权限

安全与隐私

• 不存储用户粘贴的API文档内容
• 示例代码中的Token/Key使用占位符
• 不收集或泄露API密钥信息
• 建议不在对话中发送真实的API凭证