API接口文档助手

API文档模板

# API接口文档

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

---

## 接口概览

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

---

## 通用说明

### 认证方式

Authorization: Bearer

### 请求格式

Content-Type: application/json

### 响应格式

{

"code": 0,

"message": "success",

"data": {}

}

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

---

## 接口详情

### 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"

}

]

}

}

---

## 接口变更记录

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

接口设计原则

RESTful规范

URL命名规范

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

状态码规范

安全建议

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