demo/docs/API_EXAMPLES.md

接口联调示例

启动顺序

1. 执行 src/main/resources/sql/init-auth-schema.sql
2. 执行 src/main/resources/sql/init-demo-data.sql
3. 启动应用
4. 访问 POST /api/captcha/generate
5. 使用返回的验证码登录

1. 获取验证码

接口:

POST /api/captcha/generate

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "key": "8f3b8fd4d2cf4d1ca6a4b8cf7ab33f9d",
    "image": "data:image/png;base64,..."
  }
}

2. 登录

接口:

POST /api/auth/login
Content-Type: application/json

请求体:

{
  "username": "admin",
  "password": "admin123",
  "captchaKey": "8f3b8fd4d2cf4d1ca6a4b8cf7ab33f9d",
  "captchaCode": "a8k3"
}

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "xxxxxx",
    "tokenName": "Authorization",
    "userInfo": {
      "id": 1000000000000000001,
      "username": "admin",
      "nickname": "系统管理员",
      "status": 1,
      "statusDesc": "正常"
    },
    "roles": ["ADMIN"],
    "permissions": [
      "system:user:page",
      "system:role:page",
      "system:menu:list"
    ]
  }
}

后续请求头:

Authorization: xxxxxx

3. 查询当前用户菜单

接口:

POST /api/menu/current
Authorization: xxxxxx

4. 查询当前用户权限标识

接口:

POST /api/menu/permissions/current
Authorization: xxxxxx

5. 查询前端下拉字典

查询字典类型:

POST /api/enums/list

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "enumName": "LogType",
      "enumDesc": "日志类型枚举",
      "displayName": "LogType",
      "className": "com.test.demo.enums.LogType",
      "packageName": "com.test.demo.enums",
      "valueType": "java.lang.String",
      "sourceType": "SYSTEM",
      "builtin": 1,
      "queryPath": "/api/enums/LogType"
    }
  ]
}

查询字典项:

POST /api/enums/items/LogType

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "value": "LOGIN",
      "desc": "登录日志"
    },
    {
      "value": "OPER",
      "desc": "操作日志"
    }
  ]
}

6. 新增自定义字典类型

接口:

POST /api/enum-manage/type/add
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "enumCode": "PayChannel",
  "enumName": "支付渠道",
  "enumDesc": "支付渠道字典",
  "enabled": 1,
  "sort": 1,
  "remark": "联调新增"
}

7. 新增自定义字典项

接口:

POST /api/enum-manage/item/add
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "enumCode": "PayChannel",
  "itemValue": "ALIPAY",
  "itemLabel": "支付宝",
  "itemName": "ALIPAY",
  "enabled": 1,
  "sort": 1
}

8. 启停字典类型

接口:

POST /api/enum-manage/type/enable/2033103240660238338?enabled=0
Authorization: xxxxxx

9. 启停字典项

接口:

POST /api/enum-manage/item/enable/2033103240752513025?enabled=1
Authorization: xxxxxx

10. 查询登录日志

接口:

POST /api/log/login/page
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "pageNum": 1,
  "pageSize": 10,
  "username": "admin"
}

11. 导出登录日志

接口:

POST /api/log/login/export
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "username": "admin",
  "logType": "LOGIN"
}

12. 查询操作日志

接口:

POST /api/log/oper/page
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "pageNum": 1,
  "pageSize": 10,
  "userName": "admin"
}

13. 导出操作日志

接口:

POST /api/log/oper/export
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "userName": "admin",
  "logType": "OPER"
}

14. 查询文件列表

接口:

POST /api/file/list
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "relativeDir": "",
  "recursive": true,
  "pageNum": 1,
  "pageSize": 20
}

15. 上传文件

接口:

POST /api/file/upload
Authorization: xxxxxx
Content-Type: multipart/form-data

参数:

file: 文件

16. 下载文件

接口:

GET /api/file/download/2026/03/15/demo.xlsx
Authorization: xxxxxx

17. 预览文件

接口:

GET /api/file/preview/2026/03/15/demo.xlsx

18. 导入用户

接口:

POST /api/user/import
Authorization: xxxxxx
Content-Type: multipart/form-data

参数:

file: 用户导入模板

19. 导出用户

接口:

POST /api/user/export
Authorization: xxxxxx
Content-Type: application/json

请求体:

{
  "username": "admin",
  "pageNum": 1,
  "pageSize": 10
}

20. 可选签名请求头

如果客户端要启用签名，可附带以下请求头:

X-Timestamp: 1710000000
X-Nonce: random-string
X-Sign: sha256(timestamp + nonce + body + signSecret)

签名密钥配置在:

security.sign.secret