{ "openapi": "3.1.0", "info": { "title": "Serve API", "description": "Serve应用接口文档", "contact": { "name": "杨逸" }, "version": "0.0.1-SNAPSHOT" }, "servers": [ { "url": "http://localhost:8080", "description": "Generated server url" } ], "tags": [ { "name": "AuthController", "description": "用户认证相关接口" } ], "paths": { "/user": { "get": { "tags": [ "user-controller" ], "operationId": "queryByPage", "parameters": [ { "name": "account", "in": "query", "required": true, "schema": { "type": "string", "default": "" } }, { "name": "username", "in": "query", "required": true, "schema": { "type": "string", "default": "" } }, { "name": "role", "in": "query", "required": true, "schema": { "type": "string", "default": "" } }, { "name": "enable", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageNum", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponsePageVoListUserVo" } } } } } }, "put": { "tags": [ "user-controller" ], "operationId": "edit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseBoolean" } } } } } }, "post": { "tags": [ "user-controller" ], "operationId": "add", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseBoolean" } } } } } }, "delete": { "tags": [ "user-controller" ], "operationId": "deleteById", "parameters": [ { "name": "ids", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseBoolean" } } } } } } }, "/user/updateStatus": { "put": { "tags": [ "user-controller" ], "operationId": "updateUserStatus", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserStatusDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/user/updatePassword": { "put": { "tags": [ "user-controller" ], "operationId": "updatePassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserPasswordDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/user/updateAvatar": { "put": { "tags": [ "user-controller" ], "operationId": "updateUserAvatar", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAvatarDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/meta/updateWebsiteMeta": { "post": { "tags": [ "meta-controller" ], "operationId": "updateWebsiteMeta", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteMetaDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/register": { "post": { "tags": [ "AuthController" ], "summary": "用户注册", "operationId": "register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAuthTokenVo" } } } } } } }, "/auth/login": { "post": { "tags": [ "AuthController" ], "summary": "用户登录", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAuthTokenVo" } } } } } } }, "/user/{id}": { "get": { "tags": [ "user-controller" ], "operationId": "queryById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseUserVo" } } } } } } }, "/meta/getWebsiteMeta": { "get": { "tags": [ "meta-controller" ], "operationId": "getWebsiteMeta", "responses": { "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseListFieldError" } } } }, "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } } }, "components": { "schemas": { "FieldError": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "arguments": { "type": "array", "items": { } }, "defaultMessage": { "type": "string" }, "objectName": { "type": "string" }, "field": { "type": "string" }, "rejectedValue": { }, "bindingFailure": { "type": "boolean" }, "code": { "type": "string" } } }, "ResponseListFieldError": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "type": "array", "description": "响应的具体数据", "items": { "$ref": "#/components/schemas/FieldError" } } } }, "UserDto": { "type": "object", "description": "用户新增和修改使用的DTO", "properties": { "id": { "type": "string", "description": "用户ID" }, "account": { "type": "string", "description": "用户账号", "maxLength": 20, "minLength": 4 }, "password": { "type": "string", "description": "用户密码", "maxLength": 20, "minLength": 4 }, "username": { "type": "string", "description": "用户名称", "maxLength": 32, "minLength": 2 }, "role": { "type": "string", "description": "用户角色", "maxLength": 32, "minLength": 4 } }, "required": [ "account", "password", "role", "username" ] }, "ResponseBoolean": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "type": "boolean", "description": "响应的具体数据" } } }, "UpdateUserStatusDto": { "type": "object", "description": "用户状态更新使用的DTO", "properties": { "id": { "type": "string", "description": "用户ID", "minLength": 1 }, "enable": { "type": "integer", "format": "int32", "description": "更新后的状态;1:启用,0:禁用", "maximum": 1, "minLength": 1, "minimum": 0 } }, "required": [ "enable", "id" ] }, "Response": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "description": "响应的具体数据" } } }, "UpdateUserPasswordDto": { "type": "object", "description": "用户密码修改使用的DTO", "properties": { "id": { "type": "string", "description": "用户ID", "minLength": 1 }, "password": { "type": "string", "description": "用户的当前密码", "maxLength": 20, "minLength": 4 }, "oldPassword": { "type": "string", "description": "用户的新密码", "maxLength": 20, "minLength": 4 } }, "required": [ "id", "oldPassword", "password" ] }, "UpdateUserAvatarDto": { "type": "object", "description": "更新用户头像的实体DTO", "properties": { "id": { "type": "string", "description": "用户的ID", "minLength": 1 }, "avatar": { "type": "string", "description": "头像地址的链接", "minLength": 1, "pattern": "^(https?)://[^\\s/$.?#].[^\\s]*$" } }, "required": [ "avatar", "id" ] }, "WebsiteMetaDto": { "type": "object", "description": "网站元数据DTO，用于更新网站配置信息", "properties": { "title": { "type": "string", "description": "网站标题", "maxLength": 200, "minLength": 0 }, "logo": { "type": "string", "description": "网站logo URL", "maxLength": 500, "minLength": 0 }, "statement": { "type": "string", "description": "网站声明", "maxLength": 500, "minLength": 0 }, "announcement": { "type": "string", "description": "网站公告", "maxLength": 500, "minLength": 0 } } }, "RegisterDto": { "type": "object", "description": "注册请求参数", "properties": { "account": { "type": "string", "description": "账号", "maxLength": 20, "minLength": 4 }, "password": { "type": "string", "description": "密码", "maxLength": 20, "minLength": 4 }, "username": { "type": "string", "description": "用户名", "maxLength": 32, "minLength": 2 } }, "required": [ "account", "password", "username" ] }, "AuthTokenVo": { "type": "object", "description": "登录响应", "properties": { "token": { "type": "string", "description": "JWT token" }, "userId": { "type": "integer", "format": "int64", "description": "用户ID" }, "account": { "type": "string", "description": "账号" }, "username": { "type": "string", "description": "用户名" }, "role": { "type": "string", "description": "角色" } } }, "ResponseAuthTokenVo": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "$ref": "#/components/schemas/AuthTokenVo", "description": "响应的具体数据" } } }, "LoginDto": { "type": "object", "description": "登录请求参数", "properties": { "account": { "type": "string", "description": "账号", "minLength": 1 }, "password": { "type": "string", "description": "密码", "minLength": 1 } }, "required": [ "account", "password" ] }, "PageVoListUserVo": { "type": "object", "description": "分页数据对象", "properties": { "total": { "type": "integer", "format": "int64", "description": "总数据条数" }, "data": { "type": "array", "description": "当前页的数据", "items": { "$ref": "#/components/schemas/UserVo" } } } }, "ResponsePageVoListUserVo": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "$ref": "#/components/schemas/PageVoListUserVo", "description": "响应的具体数据" } } }, "UserVo": { "type": "object", "description": "用户响应展示对象", "properties": { "id": { "type": "string", "description": "用户ID" }, "account": { "type": "string", "description": "用户账号" }, "username": { "type": "string", "description": "用户名称" }, "role": { "type": "string", "description": "用户角色" }, "avatar": { "type": "string", "description": "用户头像地址" }, "enable": { "type": "integer", "format": "int32", "description": "用户状态;0:禁用,1:启用" } } }, "ResponseUserVo": { "type": "object", "description": "后端统一的响应实体", "properties": { "code": { "type": "integer", "format": "int32", "description": "状态码;200:成功" }, "message": { "type": "string", "description": "响应附加信息" }, "data": { "$ref": "#/components/schemas/UserVo", "description": "响应的具体数据" } } } } } }