forked from datawhale/whale-town-end
feat(docs): 更新OpenAPI文档，添加验证码登录和完整接口定义
- 添加验证码登录接口：/auth/verification-code-login - 添加发送登录验证码接口：/auth/send-login-verification-code - 添加邮箱验证相关接口：send/verify/resend-email-verification - 添加调试接口：debug-verification-code, debug-clear-throttle - 添加应用状态接口：GET / - 完善所有Schema定义和响应格式 - 添加测试模式和限流错误响应 - 确保OpenAPI文档与实际API完全匹配
This commit is contained in:
moyin
@@ -15,10 +15,39 @@ servers:
|
|||||||
description: 开发环境
|
description: 开发环境
|
||||||
|
|
||||||
tags:
|
tags:
|
||||||
|
- name: app
|
||||||
|
description: 应用状态相关接口
|
||||||
- name: auth
|
- name: auth
|
||||||
description: 用户认证相关接口
|
description: 用户认证相关接口
|
||||||
|
- name: admin
|
||||||
|
description: 管理员后台相关接口
|
||||||
|
- name: user-management
|
||||||
|
description: 用户管理相关接口
|
||||||
|
|
||||||
paths:
|
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:
|
/auth/login:
|
||||||
post:
|
post:
|
||||||
tags:
|
tags:
|
||||||
@@ -259,8 +288,280 @@ paths:
|
|||||||
schema:
|
schema:
|
||||||
$ref: '#/components/schemas/ErrorResponse'
|
$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:
|
components:
|
||||||
schemas:
|
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:
|
LoginDto:
|
||||||
type: object
|
type: object
|
||||||
required:
|
required:
|
||||||
@@ -415,6 +716,64 @@ components:
|
|||||||
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||||
example: newpassword123
|
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:
|
UserInfo:
|
||||||
type: object
|
type: object
|
||||||
properties:
|
properties:
|
||||||
@@ -566,3 +925,174 @@ components:
|
|||||||
type: string
|
type: string
|
||||||
description: 错误代码
|
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