API接口文档助手

API文档模板

# API接口文档

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

---

## 接口概览

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

---

## 通用说明

### 认证方式

Authorization: Bearer <token>

### 请求格式

Content-Type: application/json

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

状态码

接口详情

1. 用户接口

1.1 获取用户信息

接口地址

GET /api/v1/users/{id}

请求参数
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | long | path | 是 | 用户ID |

请求示例

GET /api/v1/users/123

响应示例

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

错误示例

{
  "code": 3001,
  "message": "用户不存在",
  "data": null
}

1.2 创建用户

接口地址

POST /api/v1/users

请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 用户名 |
| email | string | 是 | 邮箱 |
| phone | string | 否 | 手机号 |
| password | string | 是 | 密码 |

请求示例

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

响应示例

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

2. 订单接口

2.1 订单列表

接口地址

GET /api/v1/orders

请求参数
| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| page | int | query | 否 | 页码，默认1 |
| page_size | int | query | 否 | 每页数量，默认20 |
| status | string | query | 否 | 订单状态 |

请求示例

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

响应示例

{
  "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 |
| PUT | 完整更新 | PUT /users/1 |
| PATCH | 部分更新 | PATCH /users/1 |
| DELETE | 删除 | DELETE /users/1 |

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

状态码规范

安全建议

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