# 如何让 AI 帮你写代码 / 生成接口文档

URL: https://caijiao.org/posts/31
Source: docs/posts/31.md
Description: 如何利用 AI 高效生成后端接口代码和文档，包括示例与最佳实践。

## 1. 写代码

### 提供足够的上下文

AI 写代码的质量取决于你提供的信息：

- 编程语言（如 [Python](/python/)、[JavaScript](/javascript/)、[Go](/go/)）
- 框架或库（如 FastAPI、[Express](/express/)、Vue3）
- 功能需求和业务逻辑
- 输入输出示例或数据结构

**示例 Prompt：**

```txt

请用 Python + FastAPI 写一个接口：

* GET /books 返回书籍列表
* 每本书包含 id, title, author
* 响应 JSON
````

### 分阶段生成

复杂功能可以分步生成：

1. 定义数据模型
2. 生成业务逻辑
3. 编写路由
4. 输出完整接口

## 2. 生成接口文档

### 文档结构

接口文档通常包含：

- 接口名称 / 功能
- 请求方法（GET/POST/PUT/DELETE）
- 请求 URL
- 请求参数
- 请求示例
- 响应示例
- 错误码说明

**示例接口文档（Markdown）：**

### GET /books

- **功能**：获取书籍列表  
- **请求参数**：
  - `page` (int, 可选) 页码
  - `size` (int, 可选) 每页数量
- **响应示例**：

```json
[
  {"id": 1, "title": "Python基础", "author": "张三"},
  {"id": 2, "title": "JavaScript高级", "author": "李四"}
]
````

### POST /books

- **功能**：新增书籍
- **请求参数**：

```json
{
  "title": "新书名",
  "author": "作者名"
}
```

- **响应示例**：

```json
{
  "id": 3,
  "title": "新书名",
  "author": "作者名"
}
```

## 3. 提高效率的小技巧

1. 明确输出格式：Markdown、JSON、TypeScript 类型等
2. 限制功能范围：只生成接口逻辑或只生成文档
3. 复核与优化：增加可测试示例，确保正确性
4. 连续迭代：提出修改建议，让 AI 优化文档或代码