Become a sponsor
第一个接口调试
本章节介绍如何使用 Swagger UI 在线文档调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
打开 Swagger UI
后端服务启动后，在浏览器中访问以下地址：
http://127.0.0.1:8031/docs
温馨提示
Swagger UI 是 FastAPI 自动生成的交互式 API 文档，支持在线发送请求、查看响应和调试接口。所有接口按模块分组展示，可展开查看详情。
第一步：获取验证码
登录前需要先获取图形验证码。在 Swagger UI 中找到验证码接口：
- 展开
认证管理分组 - 点击
GET /api/v1/captcha接口 - 点击
Try it out按钮 - 点击
Execute执行请求
- 响应示例
json
{
"code": 0,
"data": {
"captcha": "data:image/png;base64,iVBORw0KG...",
"key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
},
"msg": "操作成功",
"ok": true
}温馨提示
响应中的 key 是验证码的唯一标识，后续登录时需要使用。captcha 是 Base64 编码的验证码图片，可以在浏览器中直接查看。
- 记录关键信息
key: sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ
验证码图片中的文字: （查看图片获取）第二步：登录获取 Token
使用验证码和账号信息进行登录，获取 JWT 访问令牌。
- 展开
认证管理分组 - 点击
POST /api/v1/login接口 - 点击
Try it out按钮 - 在请求体中填写以下 JSON：
json
{
"username": "admin",
"password": "123456",
"code": "图片中的验证码文字",
"key": "第一步获取的key"
}- 点击
Execute执行请求
- 成功响应
json
{
"code": 0,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyZWFsbmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsImV4cCI6MTc4ODYxNDk0NiwiaWF0IjoxNzg4NjEzNzQ2fQ.xxxxxxxxxxx"
},
"msg": "登录成功",
"ok": true
}- 失败响应示例
json
{
"code": 1,
"data": null,
"msg": "验证码错误或已过期",
"ok": false
}常见登录失败原因
| 错误信息 | 原因 | 解决方式 |
|---|---|---|
| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码 |
| 账号或密码错误 | 用户名或密码不正确 | 使用默认账号 admin/123456 |
| 账号已被锁定 | 连续登录失败超过 5 次 | 等待 5 分钟后重试 |
| 参数校验失败 | 请求体格式错误 | 检查 JSON 格式是否正确 |
- 记录 Token
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...温馨提示
Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 .env 中的 JWT_EXPIRE_MINUTES 修改）。
第三步：配置 Token
在 Swagger UI 中配置 Token，后续请求会自动携带认证信息：
- 点击 Swagger UI 页面顶部的
Authorize按钮（锁形图标） - 在弹出的对话框中输入：
Bearer <你的token>例如：
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...- 点击
Authorize确认 - 点击
Close关闭对话框
温馨提示
配置 Token 后，Swagger UI 会在后续所有请求的 Authorization 请求头中自动添加 Bearer <token>，无需手动设置。
第四步：调用业务接口
Token 配置完成后，即可调用需要认证的业务接口。
- 调用用户列表接口
- 展开
用户管理分组 - 点击
GET /api/v1/user/list接口 - 点击
Try it out按钮 - 设置分页参数：
pageNo: 1
pageSize: 10- 点击
Execute执行请求
- 成功响应
json
{
"code": 0,
"data": [
{
"id": 1,
"username": "admin",
"realname": "超级管理员",
"status": 1,
"dept_id": 1,
"create_time": "2024-01-01 00:00:00"
}
],
"count": 1,
"msg": "操作成功",
"ok": true
}温馨提示
响应中的 data 是用户列表数据，count 是总记录数。分页参数 pageNo 默认为 1，pageSize 默认为 10。
接口调用流程图
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 获取验证码 │────▶│ 用户登录 │────▶│ 配置 Token │────▶│ 调用业务接口 │
│ GET /captcha │ │ POST /login │ │ Authorize │ │ GET/POST │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
key JWT Token 业务数据响应
captcha (20分钟有效)使用 curl 调试
除了 Swagger UI，也可以使用命令行工具 curl 进行接口调试：
bash
# 1. 获取验证码
curl -X GET "http://127.0.0.1:8031/api/v1/captcha" | python -m json.tool
# 2. 登录获取 Token
curl -X POST "http://127.0.0.1:8031/api/v1/login" \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "123456",
"captcha_code": "验证码文字",
"key": "获取的key"
}'
# 3. 使用 Token 调用用户列表
curl -X GET "http://127.0.0.1:8031/api/v1/user/list?pageNo=1&pageSize=10" \
-H "Authorization: Bearer <你的token>"API 响应格式说明
所有接口统一返回以下 JSON 格式：
json
// 成功响应
{
"code": 0, // 状态码：0=成功，1=失败
"data": {}, // 业务数据
"msg": "操作成功", // 提示信息
"ok": true // 业务状态
}
// 失败响应
{
"code": 1,
"data": null,
"msg": "错误信息",
"ok": false
}
// 分页响应
{
"code": 0,
"data": [], // 列表数据
"count": 100, // 总记录数
"msg": "操作成功",
"ok": true
}HTTP 状态码
无论业务成功或失败，HTTP 状态码始终为 200。业务状态通过 code 字段区分：0 表示成功，1 表示失败。
常见问题
- 接口返回 401 Unauthorized
原因：未提供 Token 或 Token 已过期
解决：重新登录获取 Token，或检查 Swagger UI 中的 Authorize 配置- 接口返回 403 Forbidden
原因：当前用户无该接口的访问权限
解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置- 接口返回 422 Validation Error
原因：请求参数校验失败
解决：检查请求体 JSON 格式和字段是否符合接口定义- Token 过期
原因：Token 超过有效期（默认 20 分钟）
解决：重新登录获取新 Token，或调用 Token 刷新接口总结
本章节通过完整的登录流程演示了如何使用 Swagger UI 调试后端 API 接口：获取验证码 → 登录获取 Token → 配置认证信息 → 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。后续开发中，可以随时通过 http://127.0.0.1:8031/docs 查看和调试所有接口。如果遇到问题，请参见 常见问题FAQ 章节。