api-doc-writer

name	api-doc-writer
description	API接口文档助手。用于编写REST API文档、定义接口规范、生成接口说明。当需要编写API文档、接口规范时触发。

API接口文档助手

API文档模板

# API接口文档

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

---

## 接口概览

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

---

## 通用说明

### 认证方式

Authorization: Bearer

### 请求格式

Content-Type: application/json

### 响应格式
```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": "[e-mail]",
    "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": "[e-mail]",
  "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规范
| 方法 | 用途 | 示例 |
|------|------|------|
| 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过期机制
• 接口调用频率限制
• 参数校验过滤