前言：

怎样生成一份简洁又好用的接口文档，调试了几次，最后发现是越简单的越好用，以下是我简化的规则文档

创建规则

规则文档包含以下内容：

• • 1、核心目标
• • 2、扫描与识别特征
• • 3、接口文档格式
• • 4、完整示例
• • 5、响应参数
• • 6、错误码识别
• • 7、注意说明（数据依赖）
• • 8、版本变更

接口文档示例：

---
alwaysApply: true
---
# 接口文档规则 (简洁版)

## 1. 核心目标
当用户要求“生成接口文档”，分析代码并按照以下的格式输出Markdown接口文档

## 2. 扫描与识别
自动判断语言，根据AST语法自动解析接口特征

## 3. 接口文档格式

```markdown

# X.X {接口名称}（如：1.1 用户登录接口）

## 1. 基本信息
**接口地址：** `/api/xxx/xxx`（绝对路径，前缀统一省略域名）
**请求方式：** GET/POST/PUT/DELETE（明确HTTP方法，严格区分大小写）
**权限要求：** `{权限标识/角色范围}`（可选，无权限要求可删除此条，示例：普通用户/管理员/无需登录）
**接口版本：** v1.0（可选，用于多版本接口区分）

## 2. 功能说明
- 详细描述接口的业务逻辑、适用场景、核心处理流程；
- 涉及复杂流程时，可插入Mermaid流程图（时序图/流程图）辅助说明。
```mermaid
# 示例：流程图（根据实际需求调整）
graph TD
A[客户端发起请求] --> B[接口网关校验]
B -->|校验通过| C[业务服务处理]
C --> D[数据库交互]
D --> E[返回处理结果]
E --> F[客户端接收响应]

## 3. 请求参数
根据请求方式和参数传递方式，分类型展示参数（如Query参数、Body参数、Header参数），同一接口有多类参数时需分开说明。

##### 3.1 Query参数（URL拼接参数，适用于GET请求）
| 参数名 | 类型 | 参数传递方式 | 必填 | 描述 | 验证规则 | 默认值 |
|--------|------|------|------|------|----------|--------|
| param1 | string | query | 是 | 参数具体含义说明（如：用户ID） | 长度1-50，仅允许字母数字 | - |
| param2 | int | query | 否 | 参数具体含义说明（如：页码） | 大于等于1，小于等于100 | 1 |

### 3.2 Body参数（请求体参数，适用于POST/PUT请求）
- 数据格式：JSON（默认）/FormData（文件上传场景）
- 参数表格：
| 参数名 | 类型 | 参数传递方式 | 必填 | 描述 | 验证规则 | 示例值 |
|--------|------|------|------|------|----------|--------|
| name | string | body | 是 | 用户名 | 长度2-20，不包含特殊字符 | "zhangsan" |
| age | int | body | 否 | 用户年龄 | 1-120 | 25 |
| address | object | body | 否 | 用户地址信息 | - | {"province":"北京","city":"北京"} |
| tags | array[string] | body | 否 | 标签列表 | 数组长度不超过10 | ["student","male"] |

### 3.3 Header参数（请求头参数）
| 参数名 | 类型 | 参数传递方式 | 必填 | 描述 | 示例值 |
|--------|------|------|------|------|--------|
| Token | string | header | 是 | 身份认证令牌 | "Bearer eyJhbGciOiJIUzI1NiJ9..." |
| Content-Type | string | header | 是 | 请求体格式 | "application/json" |

### 3.4 完整请求示例
```json
{
  "header": {
    "requestId": "ApYTlQqHAMKnt7UM9oI0CCnVDhRu1Qnc",
    "timeStamp": "20220815141453",
    "applicationId": "san-admin",
    "ip": "127.0.0.1",
    "tokenId": "xJ2SXjWHLgRbnEHd3gFINFQ1DcdBKXct"
  },
  "body": {
    "roomId": "",
    "pageNum": 1,
    "pageSize": 1
  }
}

## 4. 完整请求示例
按接口实际请求格式提供完整示例，包含请求头、请求参数（拼接/Body），明确语言/格式类型（如bash/curl、python）。

```bash
# 示例：curl请求（GET接口）
curl -X GET "https://xxx.com/api/user?param1=123&param2=1" \
-H "Token: Bearer eyJhbGciOiJIUzI1NiJ9..." \
-H "Content-Type: application/json"

## 5. 响应参数
明确响应数据格式（默认JSON），分正常响应和数据结构说明，复杂响应体需拆解说明。

##### 5.1 响应格式说明
| 字段名 | 类型 | 必返 | 描述 | 示例值 |
|--------|------|------|------|--------|
| code | int | 是 | 响应状态码（200为成功） | 200 |
| message | string | 是 | 响应提示信息（成功/错误描述） | "success" |
| data | object/array | 否 | 响应业务数据（无数据时可省略） | - |

### 5.2 响应示例（成功）
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "zhangsan",
    "age": 25,
    "address": {
      "province": "北京",
      "city": "北京"
    },
    "tags": ["student","male"],
    "createTime": "2024-01-01 12:00:00"
  }
}

### 5.3 响应示例（无业务数据）
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}


## 6. 错误码说明
列出接口常见的错误状态码、对应描述及解决方案，通用错误码（如404、500）可统一说明，接口专属错误码单独列出。

| 错误码 | 错误信息 | 错误类型 | 解决方案 |
|--------|----------|----------|----------|
| 200 | success | 成功 | - |
| 400 | 参数校验失败 | 客户端错误 | 检查参数格式、必填项是否符合规则 |
| 401 | 身份认证失效 | 客户端错误 | 重新获取Token并携带请求 |
| 403 | 无接口访问权限 | 客户端错误 | 申请对应接口的访问权限 |
| 404 | 接口地址不存在 | 客户端错误 | 核对接口地址是否正确 |
| 500 | 服务器内部错误 | 服务端错误 | 联系开发人员排查服务问题 |
| 10001 | 用户不存在 | 业务错误 | 确认用户ID是否正确 |
| 10002 | 用户名已存在 | 业务错误 | 更换其他用户名重试 |

## 7. 注意事项（可选）
- 说明接口的特殊限制（如请求频率限制：每分钟最多10次）；
- 数据安全性说明（如敏感字段加密方式、传输协议要求HTTPS）；
- 其他业务相关提示（如接口依赖的前置条件、数据返回时效）。

## 8. 变更记录（可选）
记录接口的版本迭代、变更内容、变更时间及负责人，便于追溯。

| 版本 | 变更内容 | 变更时间 | 负责人 |
|------|----------|----------|--------|
| v1.0 | 初始版本接口发布 | 2024-01-01 | 张三 |
| v1.1 | 新增tags参数，优化响应数据结构 | 2024-01-10 | 李四 |

将规则配置在cursor下，新版的cursor可能需要手动在文件夹下创建。可以在目录下的.cursor/rule 下添加，没有的话直接自己添加。

生成接口文档

生成的文档非常详细

导入到postman中

复制文档中的curl命令直接贴到postman中，方便使用

拓展：

可以根据规则再进一步进行生成rap格式、postman格式等文档。

都看到这里了，点个关注吧

1. 了解更多AI测试，请点击主页！👇