feature/verification-code-login-v1.1.0 #24
@@ -15,10 +15,39 @@ servers:
|
||||
description: 开发环境
|
||||
|
||||
tags:
|
||||
- name: app
|
||||
description: 应用状态相关接口
|
||||
- name: auth
|
||||
description: 用户认证相关接口
|
||||
- name: admin
|
||||
description: 管理员后台相关接口
|
||||
- name: user-management
|
||||
description: 用户管理相关接口
|
||||
|
||||
paths:
|
||||
/:
|
||||
get:
|
||||
tags:
|
||||
- app
|
||||
summary: 获取应用状态
|
||||
description: 返回应用的基本运行状态信息，用于健康检查和监控
|
||||
operationId: getAppStatus
|
||||
responses:
|
||||
'200':
|
||||
description: 应用状态获取成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AppStatusResponse'
|
||||
example:
|
||||
service: Pixel Game Server
|
||||
version: 1.0.0
|
||||
status: running
|
||||
timestamp: "2025-12-25T08:00:00.000Z"
|
||||
uptime: 3600
|
||||
environment: development
|
||||
storage_mode: database
|
||||
|
||||
/auth/login:
|
||||
post:
|
||||
tags:
|
||||
@@ -259,8 +288,280 @@ paths:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/send-email-verification:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 发送邮箱验证码
|
||||
description: 向指定邮箱发送验证码
|
||||
operationId: sendEmailVerification
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SendEmailVerificationDto'
|
||||
example:
|
||||
email: test@example.com
|
||||
responses:
|
||||
'200':
|
||||
description: 验证码发送成功（真实发送模式）
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/EmailVerificationResponse'
|
||||
'206':
|
||||
description: 测试模式：验证码已生成但未真实发送
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TestModeEmailVerificationResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'429':
|
||||
description: 发送频率过高
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ThrottleErrorResponse'
|
||||
|
||||
/auth/verify-email:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 验证邮箱验证码
|
||||
description: 使用验证码验证邮箱
|
||||
operationId: verifyEmail
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/EmailVerificationDto'
|
||||
example:
|
||||
email: test@example.com
|
||||
verification_code: "123456"
|
||||
responses:
|
||||
'200':
|
||||
description: 邮箱验证成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CommonResponse'
|
||||
'400':
|
||||
description: 验证码错误或已过期
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/resend-email-verification:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 重新发送邮箱验证码
|
||||
description: 重新向指定邮箱发送验证码
|
||||
operationId: resendEmailVerification
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SendEmailVerificationDto'
|
||||
example:
|
||||
email: test@example.com
|
||||
responses:
|
||||
'200':
|
||||
description: 验证码重新发送成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/EmailVerificationResponse'
|
||||
'206':
|
||||
description: 测试模式：验证码已生成但未真实发送
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TestModeEmailVerificationResponse'
|
||||
'400':
|
||||
description: 邮箱已验证或用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'429':
|
||||
description: 发送频率过高
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ThrottleErrorResponse'
|
||||
|
||||
/auth/verification-code-login:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 验证码登录
|
||||
description: 使用邮箱或手机号和验证码进行登录，无需密码
|
||||
operationId: verificationCodeLogin
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/VerificationCodeLoginDto'
|
||||
example:
|
||||
identifier: test@example.com
|
||||
verification_code: "123456"
|
||||
responses:
|
||||
'200':
|
||||
description: 验证码登录成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: 验证码错误或已过期
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/VerificationCodeLoginErrorResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/send-login-verification-code:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 发送登录验证码
|
||||
description: 向用户邮箱或手机发送登录验证码
|
||||
operationId: sendLoginVerificationCode
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SendLoginVerificationCodeDto'
|
||||
example:
|
||||
identifier: test@example.com
|
||||
responses:
|
||||
'200':
|
||||
description: 验证码发送成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/EmailVerificationResponse'
|
||||
'206':
|
||||
description: 测试模式：验证码已生成但未真实发送
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TestModeEmailVerificationResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SendLoginCodeErrorResponse'
|
||||
'429':
|
||||
description: 发送频率过高
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ThrottleErrorResponse'
|
||||
|
||||
/auth/debug-verification-code:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 调试验证码信息
|
||||
description: 获取验证码的详细调试信息（仅开发环境）
|
||||
operationId: debugVerificationCode
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SendEmailVerificationDto'
|
||||
example:
|
||||
email: test@example.com
|
||||
responses:
|
||||
'200':
|
||||
description: 调试信息获取成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DebugVerificationCodeResponse'
|
||||
|
||||
/auth/debug-clear-throttle:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 清除限流记录
|
||||
description: 清除所有限流记录（仅开发环境使用）
|
||||
operationId: clearThrottle
|
||||
responses:
|
||||
'200':
|
||||
description: 限流记录已清除
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CommonResponse'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
AppStatusResponse:
|
||||
type: object
|
||||
properties:
|
||||
service:
|
||||
type: string
|
||||
description: 服务名称
|
||||
example: Pixel Game Server
|
||||
version:
|
||||
type: string
|
||||
description: 版本号
|
||||
example: 1.0.0
|
||||
status:
|
||||
type: string
|
||||
description: 运行状态
|
||||
example: running
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 当前时间戳
|
||||
example: "2025-12-25T08:00:00.000Z"
|
||||
uptime:
|
||||
type: integer
|
||||
description: 运行时间（秒）
|
||||
example: 3600
|
||||
environment:
|
||||
type: string
|
||||
description: 运行环境
|
||||
example: development
|
||||
storage_mode:
|
||||
type: string
|
||||
description: 存储模式
|
||||
example: database
|
||||
|
||||
LoginDto:
|
||||
type: object
|
||||
required:
|
||||
@@ -415,6 +716,64 @@ components:
|
||||
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||
example: newpassword123
|
||||
|
||||
SendEmailVerificationDto:
|
||||
type: object
|
||||
required:
|
||||
- email
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址
|
||||
example: test@example.com
|
||||
|
||||
EmailVerificationDto:
|
||||
type: object
|
||||
required:
|
||||
- email
|
||||
- verification_code
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址
|
||||
example: test@example.com
|
||||
verification_code:
|
||||
type: string
|
||||
description: 6位数字验证码
|
||||
pattern: '^\d{6}$'
|
||||
example: "123456"
|
||||
|
||||
VerificationCodeLoginDto:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
- verification_code
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: 登录标识符（邮箱或手机号）
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: test@example.com
|
||||
verification_code:
|
||||
type: string
|
||||
description: 6位数字验证码
|
||||
pattern: '^\d{6}$'
|
||||
example: "123456"
|
||||
|
||||
SendLoginVerificationCodeDto:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: 邮箱或手机号
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: test@example.com
|
||||
|
||||
UserInfo:
|
||||
type: object
|
||||
properties:
|
||||
@@ -565,4 +924,175 @@ components:
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: OPERATION_FAILED
|
||||
example: OPERATION_FAILED
|
||||
|
||||
EmailVerificationResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
sent_to:
|
||||
type: string
|
||||
description: 发送目标
|
||||
example: test@example.com
|
||||
expires_in:
|
||||
type: integer
|
||||
description: 过期时间（秒）
|
||||
example: 300
|
||||
is_test_mode:
|
||||
type: boolean
|
||||
description: 是否为测试模式
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 验证码已发送，请查收邮件
|
||||
|
||||
TestModeEmailVerificationResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: false
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
verification_code:
|
||||
type: string
|
||||
description: 验证码（仅测试模式）
|
||||
example: "123456"
|
||||
sent_to:
|
||||
type: string
|
||||
description: 发送目标
|
||||
example: test@example.com
|
||||
expires_in:
|
||||
type: integer
|
||||
description: 过期时间（秒）
|
||||
example: 300
|
||||
is_test_mode:
|
||||
type: boolean
|
||||
description: 是否为测试模式
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 测试模式：验证码已生成但未真实发送
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: TEST_MODE_ONLY
|
||||
|
||||
VerificationCodeLoginErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 错误消息
|
||||
example: 验证码错误或已过期
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: VERIFICATION_CODE_LOGIN_FAILED
|
||||
|
||||
SendLoginCodeErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 错误消息
|
||||
example: 用户不存在
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: SEND_LOGIN_CODE_FAILED
|
||||
|
||||
ThrottleErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 错误消息
|
||||
example: 请求过于频繁，请稍后再试
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: TOO_MANY_REQUESTS
|
||||
throttle_info:
|
||||
type: object
|
||||
properties:
|
||||
limit:
|
||||
type: integer
|
||||
description: 限制次数
|
||||
example: 1
|
||||
window_seconds:
|
||||
type: integer
|
||||
description: 时间窗口（秒）
|
||||
example: 60
|
||||
current_requests:
|
||||
type: integer
|
||||
description: 当前请求次数
|
||||
example: 1
|
||||
reset_time:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 重置时间
|
||||
example: "2025-12-25T08:01:00.000Z"
|
||||
|
||||
DebugVerificationCodeResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
key:
|
||||
type: string
|
||||
description: Redis键名
|
||||
example: verification_code:email_verification:test@example.com
|
||||
exists:
|
||||
type: boolean
|
||||
description: 是否存在
|
||||
example: true
|
||||
ttl:
|
||||
type: integer
|
||||
description: 剩余生存时间（秒）
|
||||
example: 290
|
||||
rawData:
|
||||
type: string
|
||||
description: 原始数据
|
||||
example: '{"code":"123456","createdAt":1766649341250}'
|
||||
parsedData:
|
||||
type: object
|
||||
description: 解析后的数据
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "123456"
|
||||
createdAt:
|
||||
type: integer
|
||||
example: 1766649341250
|
||||
currentTime:
|
||||
type: integer
|
||||
description: 当前时间戳
|
||||
example: 1766649341250
|
||||
Reference in New Issue
Block a user