PRD 与文档驱动开发
3.9 API文档编写
Tip
学会用TypeScript类型定义写API文档,优先使用SDK,让AI精准理解接口。
1. 为什么要学这个?
你告诉AI:"帮我接入高德地图。"AI问:"Key在哪?API地址是什么?参数怎么传?"你丢给它一个几百页的PDF链接。AI读了一半就Token溢出了,或者开始编造参数。
原因:信息密度太低。AI不需要看"公司介绍",它只需要看Type Definitions(类型定义)。
关键问题:
- 怎么整理API文档?
- 为什么要用SDK?
- TypeScript类型定义有什么用?
Type Signature(类型签名)是AI能够理解的最高效文档。
2. 核心概念
2.1 散文 vs 类型定义
❌ 散文式文档(Bad):
"首先,你需要初始化一个对象,然后也许可以传入一个ID,如果ID不存在,可能会抛出一个错误..."
✅ 类型定义(Good):
interface MapConfig {
apiKey: string;
city: string;
zoom: number;
}
就像乐高说明书上画的零件图,精确、零歧义。
3. 怎么整理API文档?
步骤1:寻找SDK
如果官方(如Stripe、OpenAI)提供了Node.js SDK,千万不要让AI去手写HTTP请求!
SDK已经把复杂的签名、重试逻辑封装好了,而且自带类型文件(.d.ts)。
npm install openai
步骤2:提取Interface
如果必须手写Fetch(比如自家后端),请把API响应提取为TypeScript Interface,放在types/api.ts里。
// types/api.ts
export interface UserInfo {
id: number;
name: string;
vip: boolean;
}
// 告诉AI:"请参考types/api.ts里的定义来使用数据"
步骤3:建立Markdown索引
在docs/api-reference.md里记录核心接口:
# API Reference
## GET /api/user
- **Auth**: Required
- **Response**: `UserInfo` (see @types/api.ts)
## POST /api/order
- **Body**: `{ productId: string, count: number }`
4. 避坑指南
| ❌ 不要这样做 | ✅ 应该这样做 | 为什么 |
|---|---|---|
| 让AI猜参数 | 提供类型定义,把.d.ts文件喂给它 | AI经常把userId猜成uid或user_id |
| 从不用SDK | 优先找SDK,站在巨人的肩膀上 | 手写Fetch代码量是SDK的5倍 |
| 文档不更新 | 使用Swagger等自动化工具生成文档 | 代码改了,文档没改会误导AI |
5. 真实案例
Story
宜家(IKEA)的无字说明书
宜家卖遍全球,但它的说明书里几乎没有一个文字,只有图片、数字和箭头的组合。为什么?因为文字有语言隔阂(英语、法语、中文),而图形逻辑是通用的。一个瑞典人画的安装图,一个巴西人能看懂,一个日本人也能看懂。
Vibe心法:优先用SDK,其次用TypeScript Interface——类型定义是"无语言"的通用说明书。
6. 本章小结
- 🔧 SDK > HTTP:优先用官方SDK
- 📝 Types > Text:代码类型定义比文字描述更精准
- 📚 IKEA哲学:用结构化语言(TS/Markdown)消除歧义
- ⚠️ 避免猜参数:提供.d.ts类型文件
- 🔄 自动化文档:使用Swagger等工具生成文档