API 文档模板

🎯 模板用途：本模板用于创建标准化的 API 接口文档，为 Cursor AI 提供 API 文档编写和维护的参考格式

📋 文档说明

适用场景

新增 API 接口时创建文档
现有 API 接口修改时更新文档
为 Cursor AI 提供接口开发上下文

使用方法

复制本模板内容
替换所有 [占位符] 为实际内容
根据实际接口情况调整结构
确保示例代码可以正常运行

🔌 [模块名称] API 接口文档

模块概述

模块名称：[模块英文名] / [模块中文名]
基础路径：/api/[module]
版本：v1.0
负责人：[开发负责人]
更新时间：[最后更新时间]

模块功能

[模块的主要功能描述，包括业务价值和技术特点]

权限说明

权限前缀：[module]:
权限列表：
- [module]:list - 查询权限
- [module]:add - 新增权限
- [module]:edit - 编辑权限
- [module]:remove - 删除权限

📊 接口概览

接口分类

基础 CRUD 接口

接口名称	HTTP 方法	路径	权限要求	功能描述
查询[实体]列表	GET	`/api/[module]/list`	`[module]:list`	分页查询[实体]列表
查询[实体]详情	GET	`/api/[module]/{id}`	`[module]:list`	根据 ID 查询[实体]详情
新增[实体]	POST	`/api/[module]`	`[module]:add`	创建新的[实体]
修改[实体]	PUT	`/api/[module]`	`[module]:edit`	更新[实体]信息
删除[实体]	DELETE	`/api/[module]/{ids}`	`[module]:remove`	批量删除[实体]

业务逻辑接口

接口名称	HTTP 方法	路径	权限要求	功能描述
[业务接口 1]	[方法]	`/api/[module]/[action1]`	`[权限]`	[功能描述]
[业务接口 2]	[方法]	`/api/[module]/[action2]`	`[权限]`	[功能描述]
[业务接口 3]	[方法]	`/api/[module]/[action3]`	`[权限]`	[功能描述]

通用响应格式

成功响应

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        // 响应数据
    }
}

分页响应

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        // 数据列表
    ],
    "total": 100
}

错误响应

{
    "code": 400001,
    "msg": "参数错误",
    "data": null
}

🔍 接口详细说明

1. 查询[实体]列表

接口信息

接口地址: GET /api/[module]/list

接口描述: 分页查询[实体]列表，支持多条件筛选

权限要求: [module]:list

请求参数

参数名	类型	必填	说明	示例值
pageNum	Integer	N	页码，默认 1	1
pageSize	Integer	N	每页大小，默认 10	10
[field1]	String	N	[字段 1 说明]	"示例值"
[field2]	Integer	N	[字段 2 说明]	1
status	Integer	N	状态：1 启用，0 禁用	1
beginTime	String	N	开始时间	"2024-01-01"
endTime	String	N	结束时间	"2024-01-31"

请求示例

curl -X GET "http://localhost:8080/api/[module]/list?pageNum=1&pageSize=10&status=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "id": 1,
            "[field1]": "示例值1",
            "[field2]": 1,
            "status": 1,
            "createBy": 1,
            "createTime": "2024-01-01 10:00:00",
            "updateBy": 1,
            "updateTime": "2024-01-01 10:00:00"
        },
        {
            "id": 2,
            "[field1]": "示例值2",
            "[field2]": 2,
            "status": 1,
            "createBy": 1,
            "createTime": "2024-01-01 11:00:00",
            "updateBy": 1,
            "updateTime": "2024-01-01 11:00:00"
        }
    ],
    "total": 100
}

错误码

错误码	说明	解决方案
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限
400001	参数错误	检查请求参数格式

2. 查询[实体]详情

接口信息

接口地址: GET /api/[module]/{id}

接口描述: 根据 ID 查询[实体]的详细信息

权限要求: [module]:list

路径参数

参数名	类型	必填	说明	示例值
id	Long	Y	[实体]ID	1

请求示例

curl -X GET "http://localhost:8080/api/[module]/1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "id": 1,
        "[field1]": "示例值",
        "[field2]": 1,
        "status": 1,
        "remark": "备注信息",
        "createBy": 1,
        "createTime": "2024-01-01 10:00:00",
        "updateBy": 1,
        "updateTime": "2024-01-01 10:00:00"
    }
}

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

3. 新增[实体]

接口信息

接口地址: POST /api/[module]

接口描述: 创建新的[实体]记录

权限要求: [module]:add

请求参数

参数名	类型	必填	说明	示例值
[field1]	String	Y	[字段 1 说明]	"示例值"
[field2]	Integer	Y	[字段 2 说明]	1
status	Integer	N	状态：1 启用，0 禁用，默认 1	1
remark	String	N	备注信息	"备注内容"

请求体

{
    "[field1]": "示例值",
    "[field2]": 1,
    "status": 1,
    "remark": "备注信息"
}

请求示例

curl -X POST "http://localhost:8080/api/[module]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "[field1]": "示例值",
    "[field2]": 1,
    "status": 1,
    "remark": "备注信息"
  }'

响应示例

{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "id": 3
    }
}

错误码

错误码	说明	解决方案
400001	参数错误	检查必填参数是否缺失
400002	数据已存在	检查唯一字段是否重复
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

参数验证规则

[field1]: 长度 2-50 字符，不能为空
[field2]: 必须为正整数
status: 只能为 0 或 1
remark: 最大长度 500 字符

4. 修改[实体]

接口信息

接口地址: PUT /api/[module]

接口描述: 更新[实体]信息

权限要求: [module]:edit

请求参数

参数名	类型	必填	说明	示例值
id	Long	Y	[实体]ID	1
[field1]	String	Y	[字段 1 说明]	"示例值"
[field2]	Integer	Y	[字段 2 说明]	1
status	Integer	N	状态：1 启用，0 禁用	1
remark	String	N	备注信息	"备注内容"

请求体

{
    "id": 1,
    "[field1]": "修改后的值",
    "[field2]": 2,
    "status": 1,
    "remark": "修改后的备注"
}

请求示例

curl -X PUT "http://localhost:8080/api/[module]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "[field1]": "修改后的值",
    "[field2]": 2,
    "status": 1,
    "remark": "修改后的备注"
  }'

响应示例

{
    "code": 200,
    "msg": "修改成功",
    "data": null
}

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
400001	参数错误	检查参数格式是否正确
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

5. 删除[实体]

接口信息

接口地址: DELETE /api/[module]/{ids}

接口描述: 批量删除[实体]，支持逻辑删除

权限要求: [module]:remove

路径参数

参数名	类型	必填	说明	示例值
ids	String	Y	[实体]ID 列表，多个用逗号分隔	"1,2,3"

请求示例

curl -X DELETE "http://localhost:8080/api/[module]/1,2,3" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "删除成功",
    "data": {
        "successCount": 2,
        "failCount": 1,
        "failIds": [3]
    }
}

错误码

错误码	说明	解决方案
400001	参数错误	检查 ID 格式是否正确
400003	数据被引用	请先删除关联数据
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

🎯 业务逻辑接口

1. [业务接口 1 名称]

接口信息

接口地址: [HTTP方法] /api/[module]/[action]

接口描述: [详细的业务功能描述]

权限要求: [权限代码]

业务流程

[业务步骤 1]
[业务步骤 2]
[业务步骤 3]

请求参数

参数名	类型	必填	说明	示例值
[param1]	[类型]	[Y/N]	[参数说明]	[示例值]
[param2]	[类型]	[Y/N]	[参数说明]	[示例值]

请求示例

curl -X [方法] "http://localhost:8080/api/[module]/[action]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "[param1]": "[值1]",
    "[param2]": "[值2]"
  }'

响应示例

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "[result1]": "[结果值1]",
        "[result2]": "[结果值2]"
    }
}

业务规则

[业务规则 1]
[业务规则 2]
[业务规则 3]

注意事项

[注意事项 1]
[注意事项 2]

📋 数据字典

[实体名称] 状态枚举

值	名称	说明
0	禁用	不可使用
1	启用	正常使用

[其他枚举名称]

值	名称	说明
[值 1]	[名称 1]	[说明 1]
[值 2]	[名称 2]	[说明 2]

🔧 SDK 使用示例

Java SDK

// 查询列表
[Module]QueryBo queryBo = new [Module]QueryBo();
queryBo.setStatus(1);
PageQuery pageQuery = new PageQuery(1, 10);
Result<PageResult<[Module]Vo>> result = [module]Api.list(queryBo, pageQuery);

// 新增记录
[Module]Bo [module]Bo = new [Module]Bo();
[module]Bo.set[Field1]("示例值");
[module]Bo.set[Field2](1);
Result<Long> addResult = [module]Api.add([module]Bo);

// 修改记录
[module]Bo.setId(1L);
[module]Bo.set[Field1]("修改后的值");
Result<Void> updateResult = [module]Api.update([module]Bo);

JavaScript SDK

// 查询列表
const queryParams = {
  pageNum: 1,
  pageSize: 10,
  status: 1
};
const listResult = await [module]Api.list(queryParams);

// 新增记录
const [module]Data = {
  [field1]: "示例值",
  [field2]: 1,
  status: 1
};
const addResult = await [module]Api.add([module]Data);

// 修改记录
[module]Data.id = 1;
[module]Data.[field1] = "修改后的值";
const updateResult = await [module]Api.update([module]Data);

🧪 测试用例

接口测试

// Jest 测试示例
describe('[Module] API Tests', () => {
  test('查询列表接口', async () => {
    const response = await request(app)
      .get('/api/[module]/list')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.rows).toBeDefined();
    expect(response.body.total).toBeGreaterThanOrEqual(0);
  });

  test('新增接口', async () => {
    const [module]Data = {
      [field1]: "测试值",
      [field2]: 1
    };

    const response = await request(app)
      .post('/api/[module]')
      .set('Authorization', `Bearer ${token}`)
      .send([module]Data)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.data.id).toBeDefined();
  });
});

🔄 版本历史

v1.0.0 - 2024-01-01

✅ 初始版本发布
✅ 完成基础 CRUD 接口
✅ 完成核心业务接口

v1.0.1 - 2024-01-15

🔧 优化查询接口性能
🐛 修复删除接口的权限检查问题
📚 补充接口文档和示例

v1.1.0 - 2024-02-01

✨ 新增[新功能 1]接口
✨ 新增[新功能 2]接口
🔧 优化错误处理机制

📖 相关文档

数据库设计：数据库设计文档
业务需求：业务需求文档
技术架构：技术架构文档
开发规范：开发规范文档

📞 联系方式

开发团队：[团队名称]
负责人：[负责人姓名]
邮箱：[联系邮箱]
文档维护：实时更新，如有问题请及时反馈

📌 重要提醒：

所有接口都需要先登录获取 token
请求头必须包含 Authorization: Bearer {token}
参数验证失败会返回详细的错误信息
生产环境请使用 HTTPS 协议

API文档模板.md 15 KB Verlauf Originalformat

API 文档模板

📋 文档说明

适用场景

使用方法

🔌 [模块名称] API 接口文档

模块概述

模块功能

权限说明

📊 接口概览

接口分类

基础 CRUD 接口

业务逻辑接口

通用响应格式

成功响应

分页响应

错误响应

🔍 接口详细说明

1. 查询[实体]列表

接口信息

请求参数

请求示例

响应示例

错误码

2. 查询[实体]详情

接口信息

路径参数

请求示例

响应示例

错误码

3. 新增[实体]

接口信息

请求参数

请求体

请求示例

响应示例

错误码

参数验证规则

4. 修改[实体]

接口信息

请求参数

请求体

请求示例

响应示例

错误码

5. 删除[实体]

接口信息

路径参数

请求示例

响应示例

错误码

🎯 业务逻辑接口

1. [业务接口 1 名称]

接口信息

业务流程

请求参数

请求示例

响应示例

业务规则

注意事项

📋 数据字典

[实体名称] 状态枚举

[其他枚举名称]

🔧 SDK 使用示例

Java SDK

JavaScript SDK

🧪 测试用例

接口测试

🔄 版本历史

v1.0.0 - 2024-01-01

v1.0.1 - 2024-01-15

v1.1.0 - 2024-02-01

📖 相关文档

📞 联系方式

API文档模板.md 15 KB

Verlauf Originalformat