springboot-template/API_DOCUMENT.md

API 接口文档

Base URL: http://localhost:8080/api/v1

在线文档: http://localhost:8080/swagger-ui/index.html

通用说明

响应格式

所有接口统一返回 RestBean：

{
  "status": 200,
  "message": "success",
  "data": {}
}

认证方式

需要认证的接口在请求头中携带 JWT Token：

Authorization: Bearer <token>

登录/注册接口会返回 Token。

---

用户接口

注册

POST /api/v1/user/register

公开接口，无需认证。

请求体：

字段	类型	必填	说明
username	String	是	用户名，2-50 位
password	String	是	密码，6-64 位
email	String	否	邮箱

请求示例：

{
  "username": "testuser",
  "password": "123456",
  "email": "test@example.com"
}

响应示例：

{
  "status": 200,
  "message": "success",
  "data": "eyJhbGciOiJIUzUxMiJ9..."
}

---

登录

POST /api/v1/user/login

公开接口，无需认证。

请求体：

字段	类型	必填	说明
username	String	是	用户名
password	String	是	密码

请求示例：

{
  "username": "testuser",
  "password": "123456"
}

响应示例：

{
  "status": 200,
  "message": "success",
  "data": "eyJhbGciOiJIUzUxMiJ9..."
}

---

获取用户信息

GET /api/v1/user/info

需要认证。

请求头：

Authorization: Bearer <token>

响应示例：

{
  "status": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "status": 1,
    "role": "USER",
    "createdAt": "2026-03-31 08:00:00",
    "updatedAt": "2026-03-31 08:00:00"
  }
}

---

发送密码找回验证码

POST /api/v1/user/password-reset/request

公开接口，无需认证。

请求体：

字段	类型	必填	说明
email	String	是	已注册的邮箱

请求示例：

{
  "email": "test@example.com"
}

频率限制：

• 两次请求间隔至少 60 秒
• 同一邮箱 1 小时内最多 5 次

---

验证码重置密码

POST /api/v1/user/password-reset/confirm

公开接口，无需认证。

请求体：

字段	类型	必填	说明
email	String	是	邮箱
code	String	是	6 位数字验证码
newPassword	String	是	新密码，6-64 位

请求示例：

{
  "email": "test@example.com",
  "code": "123456",
  "newPassword": "newpass123"
}

验证码限制：

• 有效期 10 分钟
• 最多尝试 5 次

---

用户列表（管理员）

GET /api/v1/user/list

需要认证 + ADMIN 角色。

请求参数：

参数	类型	必填	说明
page	Integer	否	页码，默认 1
size	Integer	否	每页条数，默认 10
keyword	String	否	搜索关键词（用户名/邮箱）
role	String	否	角色筛选（USER/ADMIN）
status	Integer	否	状态筛选（1=正常 0=禁用）

响应示例：

{
  "status": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "status": 1,
        "role": "ADMIN",
        "createdAt": "2026-03-31 08:00:00",
        "updatedAt": "2026-03-31 08:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10
  }
}

---

更新用户状态（管理员）

PUT /api/v1/user/{userId}/status

需要认证 + ADMIN 角色。

路径参数：

参数	类型	说明
userId	Long	用户 ID

请求体：

字段	类型	必填	说明
status	Integer	是	1=启用，0=禁用

请求示例：

{
  "status": 0
}

不允许修改自己的状态。

---

更新用户角色（管理员）

PUT /api/v1/user/{userId}/role

需要认证 + ADMIN 角色。

路径参数：

参数	类型	说明
userId	Long	用户 ID

请求体：

字段	类型	必填	说明
role	String	是	角色名称：USER 或 ADMIN

请求示例：

{
  "role": "ADMIN"
}

不允许修改自己的角色。

---

错误码

错误码	说明
200	成功
400	参数错误 / 请求格式错误
403	权限不足 / 账号被禁用
404	数据不存在
500	系统异常

业务错误码：

错误码	说明
1001	用户不存在
1002	密码错误
1003	账号已被锁定