From 7385c63ffd4fa8c3d58066f0d2297bbb6c72d084 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Thu, 25 Dec 2025 16:11:07 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0OpenAPI?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E7=A0=81=E7=99=BB=E5=BD=95=E5=92=8C=E5=AE=8C=E6=95=B4=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加验证码登录接口：/auth/verification-code-login - 添加发送登录验证码接口：/auth/send-login-verification-code - 添加邮箱验证相关接口：send/verify/resend-email-verification - 添加调试接口：debug-verification-code, debug-clear-throttle - 添加应用状态接口：GET / - 完善所有Schema定义和响应格式 - 添加测试模式和限流错误响应 - 确保OpenAPI文档与实际API完全匹配 --- docs/api/openapi.yaml | 532 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 531 insertions(+), 1 deletion(-) diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 7151c11..e4774d3 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -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 \ No newline at end of file + 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 \ No newline at end of file