api-doc-writer（API DOC 写作）

API接口文档助手

API文档模板

# API接口文档

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

---

## 接口概览

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

---

## 通用说明

### 认证方式

Authorization: Bearer <token>

### 请求格式

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过期机制
• 接口调用频率限制
• 参数校验过滤