API接口文档助手#

API文档模板#

markdown

# API接口文档

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

---

## 接口概览

| 模块 | 接口数 | 负责人 |
|------|--------|--------|
| 用户模块 | 5 | @xxx |
| 订单模块 | 8 | @xxx |
| 支付模块 | 4 | @xxx |

---

## 通用说明

### 认证方式

Authorization: Bearer

text

### 请求格式

Content-Type: application/json

text

### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}

状态码#

状态码说明0成功1001参数错误2001未授权3001资源不存在5001服务器错误

---

接口详情#

1. 用户接口#

1.1 获取用户信息

接口地址

text

GET /api/v1/users/{id}

请求参数

参数名类型位置必填说明idlongpath是用户ID

请求示例

text

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 创建用户

接口地址

text

POST /api/v1/users

请求参数

参数名类型必填说明namestring是用户名emailstring是邮箱phonestring否手机号passwordstring是密码

请求示例

json

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "password": "123456"
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

---

2. 订单接口#

2.1 订单列表

接口地址

text

GET /api/v1/orders

请求参数

参数名类型位置必填说明pageintquery否页码，默认1page_sizeintquery否每页数量，默认20statusstringquery否订单状态

请求示例

text

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"
      }
    ]
  }
}

---

接口变更记录#

版本日期变更内容变更人V1.0YYYY-MM-DD初始版本@xxxV1.1YYYY-MM-DD新增xxx接口@xxxtext

## 接口设计原则

### RESTful规范
| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询 | GET /users |
| POST | 创建 | POST /users |
| PUT | 完整更新 | PUT /users/1 |
| PATCH | 部分更新 | PATCH /users/1 |
| DELETE | 删除 | DELETE /users/1 |

### URL命名规范
```markdown
- 使用名词复数：/users
- 使用小写：/user-info
- 使用连字符分隔：/order-details
- 避免动词：不用 /getUser

状态码规范#

类别状态码说明1xx信息接收的请求正在处理2xx成功请求正常处理完毕3xx重定向需要附加操作完成请求4xx客户端错误请求有语法错误5xx服务器错误服务器处理出错

安全建议#

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