83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# Hertz Studio Django 验证码模块接口文档
|
||
|
||
- 基础路径: `/api/captcha/`
|
||
- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
- 路由挂载: 项目主路由中已通过 `path('api/captcha/', include('hertz_studio_django_captcha.urls'))` 挂载（`hertz_server_django/urls.py:28`）。
|
||
- 认证说明: 接口允许匿名访问（`AllowAny`），不需要登录（`hertz_studio_django_captcha/api_views.py:18`, `hertz_studio_django_captcha/api_views.py:60`）。
|
||
- 验证接口说明: 独立的验证码验证接口已删除，验证逻辑集成到具体业务接口（`hertz_studio_django_captcha/api_views.py:54`）。
|
||
|
||
|
||
## 一、生成验证码
|
||
|
||
### 生成新的验证码
|
||
- 方法: `POST`
|
||
- 路径: `/api/captcha/generate/`
|
||
- 认证: 不需要登录
|
||
- 实现: `CaptchaGenerateAPIView.post`（`hertz_studio_django_captcha/api_views.py:38`）
|
||
- 请求示例:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/captcha/generate/"
|
||
```
|
||
- 返回示例:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "验证码生成成功",
|
||
"data": {
|
||
"captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
|
||
"image_data": "data:image/png;base64,iVBORw0KGgo...",
|
||
"expires_in": 300
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## 二、刷新验证码
|
||
|
||
### 刷新已有验证码，生成新图像
|
||
- 方法: `POST`
|
||
- 路径: `/api/captcha/refresh/`
|
||
- 认证: 不需要登录
|
||
- 请求体: `application/json`
|
||
- 字段: `captcha_id` 旧验证码ID
|
||
- 实现: `CaptchaRefreshAPIView.post`（`hertz_studio_django_captcha/api_views.py:84`）
|
||
- 请求示例:
|
||
```http
|
||
POST /api/captcha/refresh/
|
||
Content-Type: application/json
|
||
|
||
{"captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"}
|
||
```
|
||
- 返回示例:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "验证码刷新成功",
|
||
"data": {
|
||
"captcha_id": "f2b3c4d5-e6f7-8901-bcde-0123456789ab",
|
||
"image_data": "data:image/png;base64,iVBORw0KGgo...",
|
||
"expires_in": 300
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## 三、错误响应示例
|
||
- 参数不完整（刷新接口）:
|
||
```json
|
||
{"success": false, "code": 400, "message": "参数不完整"}
|
||
```
|
||
- 生成/刷新失败（异常信息）：
|
||
```json
|
||
{"success": false, "code": 500, "message": "验证码生成失败", "error": "<错误信息>"}
|
||
``` |