API接口文档助手

API文档模板

markdown

API接口文档

版本：V1.0
更新日期：YYYY-MM-DD
维护人：XXX

接口概览

通用说明

认证方式

Authorization: Bearer

请求格式

Content-Type: application/json

响应格式

状态码

状态码	说明
0	成功
1001

参数错误 |

接口详情

1. 用户接口

1.1 获取用户信息

接口地址

GET /api/v1/users/{id}

请求参数

请求示例

GET /api/v1/users/123

响应示例
json
{
code: 0,
message: success,
data: {
id: 123,
name: 张三,
email: zhangsan@example.com,
phone: 13800138000,
created_at: 2024-01-01 10:00:00
}
}

错误示例
json
{
code: 3001,
message: 用户不存在,
data: null
}

1.2 创建用户

接口地址

POST /api/v1/users

请求参数

请求示例
json
{
name: 张三,
email: zhangsan@example.com,
phone: 13800138000,
password: 123456
}

响应示例
json
{
code: 0,
message: success,
data: {
id: 123,
name: 张三
}
}

2. 订单接口

2.1 订单列表

接口地址

GET /api/v1/orders

请求参数

请求示例

GET /api/v1/orders?page=1&page_size=10&status=paid

响应示例
json
{
code: 0,
message: success,
data: {
total: 100,
page: 1,
page_size: 10,
list: [
{
id: ORD202401010001,
user_id: 123,
amount: 100.00,
status: paid,
created_at: 2024-01-01 10:00:00
}
]
}
}

接口变更记录

接口设计原则

RESTful规范

方法	用途	示例
GET	查询	GET /users
POST

创建 | POST /users |

URL命名规范

• - 使用名词复数：/users
• 使用小写：/user-info
• 使用连字符分隔：/order-details
• 避免动词：不用 /getUser

状态码规范

类别	状态码	说明
1xx	信息	接收的请求正在处理
2xx

成功 | 请求正常处理完毕 |

安全建议

• - 敏感信息加密传输
• 身份验证Token过期机制
• 接口调用频率限制
• 参数校验过滤