From 5026c9b39cf26add89d917dbfdfe029149af5555 Mon Sep 17 00:00:00 2001 From: Azure <983547216@qq.com> Date: Tue, 16 Jun 2026 17:08:49 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0json?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/openapi.json | 128 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 112 insertions(+), 16 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 7ccb466..b684ff0 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -3,7 +3,7 @@ "info": { "title": "WebGame 后端接口文档", "version": "1.0.0", - "description": "WebGame 游戏后端 REST API 接口文档" + "description": "WebGame 游戏后端 REST API 接口文档。认证采用双 Token 机制：Access Token（30 分钟有效，每次请求携带） + Refresh Token（30 天有效，仅用于刷新 Access Token）。" }, "servers": [ { @@ -12,15 +12,15 @@ } ], "tags": [ - { "name": "账号", "description": "账号相关接口（登录、注册，无需认证）" }, - { "name": "用户", "description": "用户相关接口（需登录认证）" } + { "name": "账号", "description": "账号相关接口（登录、注册、刷新令牌，无需认证）" }, + { "name": "用户", "description": "用户相关接口（需 Access Token 认证）" } ], "paths": { "/account/login": { "post": { "tags": ["账号"], "summary": "用户登录", - "description": "使用用户名和密码进行登录认证，成功返回 Sa-Token 令牌。该接口无需登录即可调用。", + "description": "使用用户名和密码进行登录认证，成功返回 Access Token 和 Refresh Token。该接口无需登录即可调用。", "operationId": "login", "security": [], "requestBody": { @@ -37,7 +37,7 @@ }, "responses": { "200": { - "description": "登录成功，返回 token", + "description": "登录成功，返回双 Token", "content": { "application/json": { "schema": { @@ -55,7 +55,8 @@ "code": 0, "message": "success", "data": { - "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" } } } @@ -70,7 +71,7 @@ "post": { "tags": ["账号"], "summary": "用户注册", - "description": "注册新账号。用户名长度 3-32 位，密码长度 6-64 位。注册成功后自动登录并返回 token。该接口无需登录即可调用。", + "description": "注册新账号。用户名长度 3-32 位，密码长度 6-64 位。注册成功后自动登录并返回双 Token。该接口无需登录即可调用。", "operationId": "register", "security": [], "requestBody": { @@ -87,7 +88,7 @@ }, "responses": { "200": { - "description": "注册成功，自动登录返回 token", + "description": "注册成功，自动登录返回双 Token", "content": { "application/json": { "schema": { @@ -105,7 +106,58 @@ "code": 0, "message": "success", "data": { - "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + } + } + } + } + }, + "400": { "$ref": "#/components/responses/BadRequest" }, + "500": { "$ref": "#/components/responses/InternalError" } + } + } + }, + "/account/refresh": { + "post": { + "tags": ["账号"], + "summary": "刷新 Access Token", + "description": "当 Access Token 过期（30 分钟）后，使用 Refresh Token 换取新的 Access Token。Refresh Token 保持不变，仅在满 30 天或重新登录时更新。该接口无需登录即可调用。", + "operationId": "refresh", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" }, + "example": { + "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + } + } + } + }, + "responses": { + "200": { + "description": "刷新成功，返回新的 Access Token 和原 Refresh Token", + "content": { + "application/json": { + "schema": { + "allOf": [ + { "$ref": "#/components/schemas/ApiResponse" }, + { + "type": "object", + "properties": { + "data": { "$ref": "#/components/schemas/LoginResponse" } + } + } + ] + }, + "example": { + "code": 0, + "message": "success", + "data": { + "accessToken": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", + "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" } } } @@ -120,7 +172,7 @@ "get": { "tags": ["用户"], "summary": "获取当前登录用户信息", - "description": "根据请求头中的 saToken 获取当前登录用户的详细信息，包括昵称、头像、个性签名、年龄、性别、生日。需登录认证。", + "description": "根据请求头中的 saToken（Access Token）获取当前登录用户的详细信息，包括昵称、头像、个性签名、年龄、性别、生日。需登录认证。", "operationId": "getUserInfo", "security": [{ "saToken": [] }], "responses": { @@ -166,7 +218,7 @@ "type": "apiKey", "in": "header", "name": "saToken", - "description": "Sa-Token 认证令牌。登录/注册成功后返回的 token 值，在后续请求的 Header 中携带。" + "description": "Access Token（登录/注册/刷新接口返回的 accessToken 值）。有效期 30 分钟，过期后使用 /account/refresh 接口获取新 Token。" } }, "schemas": { @@ -232,15 +284,33 @@ } } }, + "RefreshTokenRequest": { + "type": "object", + "description": "刷新令牌请求体", + "required": ["refreshToken"], + "properties": { + "refreshToken": { + "type": "string", + "description": "刷新令牌，登录/注册时返回的 refreshToken 值，不能为空", + "minLength": 1, + "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + } + } + }, "LoginResponse": { "type": "object", - "description": "登录或注册成功时返回的认证令牌", - "required": ["token"], + "description": "登录、注册或刷新令牌成功时返回的认证令牌对", + "required": ["accessToken", "refreshToken"], "properties": { - "token": { + "accessToken": { "type": "string", - "description": "Sa-Token 认证令牌（UUID 格式）。后续请求需在 Header 中通过 saToken 字段携带此值。", + "description": "Access Token（UUID 格式），有效期 30 分钟。后续请求需在 Header 中通过 saToken 字段携带此值。过期后使用 /account/refresh 接口刷新。", "example": "12345678-1234-1234-1234-123456789abc" + }, + "refreshToken": { + "type": "string", + "description": "Refresh Token（64 位十六进制随机字符串），有效期 30 天。仅用于 /account/refresh 接口换取新的 Access Token。刷新时不变，重新登录时替换。", + "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" } } }, @@ -348,6 +418,22 @@ "data": null } }, + "refreshTokenInvalid": { + "summary": "刷新令牌无效或已过期", + "value": { + "code": 1003, + "message": "刷新令牌无效或已过期", + "data": null + } + }, + "refreshTokenMissing": { + "summary": "缺少刷新令牌", + "value": { + "code": 1004, + "message": "缺少刷新令牌", + "data": null + } + }, "userNotFound": { "summary": "用户不存在", "value": { @@ -361,7 +447,7 @@ } }, "Unauthorized": { - "description": "未登录或 token 无效（HTTP 200 但 code=401）", + "description": "未登录或 Access Token 无效/过期（HTTP 200 但 code=401）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, @@ -450,6 +536,16 @@ "message": "用户名或密码错误", "description": "登录时用户名或密码不匹配" }, + "REFRESH_TOKEN_INVALID": { + "code": 1003, + "message": "刷新令牌无效或已过期", + "description": "Refresh Token 不存在或已过期（30 天），需重新登录" + }, + "REFRESH_TOKEN_MISSING": { + "code": 1004, + "message": "缺少刷新令牌", + "description": "请求体中的 refreshToken 字段为空" + }, "USER_NOT_FOUND": { "code": 2001, "message": "用户不存在",