{ "openapi": "3.0.0", "info": { "title": "InterConnect-Server API", "version": "1.0.0", "description": "InterConnect-Server 是一个 Minecraft WebSocket API 服务器，提供 API Key 管理、事件广播、服务器命令等功能。\n\n权限说明：\n- **Admin Key**: `mc_admin_` 前缀，拥有完整管理权限。\n- **Regular Key**: `mc_key_` 前缀，可查看/管理关联的 Server Key，发送服务器命令。\n- **Server Key**: `mc_server_` 前缀，仅用于插件/Mod 配置，用于认证和事件上报。" }, "servers": [ { "url": "http://localhost:8000", "description": "本地服务器" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "使用 API Key 进行认证 (Bearer Token)" } }, "schemas": { "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "keyPrefix": { "type": "string", "enum": ["mc_admin_", "mc_key_", "mc_server_"] }, "keyType": { "type": "string", "enum": ["admin", "regular", "server"] }, "serverId": { "type": "string", "nullable": true }, "regularKeyId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsed": { "type": "string", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean" } } }, "ApiKeyWithSecret": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "key": { "type": "string", "description": "原始 API Key，仅在创建时返回一次" } } } ] }, "CreateKeyRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "key_type": { "type": "string", "enum": ["regular", "admin"], "default": "regular" }, "server_id": { "type": "string" } } }, "CreateServerKeyRequest": { "type": "object", "required": ["name", "regular_key_id"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "server_id": { "type": "string" }, "regular_key_id": { "type": "string", "description": "关联的 Regular Key ID" } } }, "Event": { "type": "object", "required": ["event_type", "server_name", "timestamp", "data"], "properties": { "event_type": { "type": "string", "description": "事件类型 (e.g., player_join, player_leave, message, ai_chat)" }, "server_name": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "事件具体数据" } } }, "CommandRequest": { "type": "object", "required": ["command"], "properties": { "command": { "type": "string" }, "server_id": { "type": "string", "description": "仅 Admin Key 需要/可以指定" } } }, "AiConfig": { "type": "object", "properties": { "apiUrl": { "type": "string" }, "modelId": { "type": "string" }, "apiKey": { "type": "string", "description": "部分隐藏的 API Key" }, "enabled": { "type": "boolean" }, "systemPrompt": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AiConfigUpdateRequest": { "type": "object", "properties": { "api_url": { "type": "string" }, "model_id": { "type": "string" }, "api_key": { "type": "string" }, "enabled": { "type": "boolean" }, "system_prompt": { "type": "string" } } }, "AiChatRequest": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string" }, "player_name": { "type": "string" }, "server_id": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "paths": { "/health": { "get": { "summary": "健康检查", "description": "获取服务器状态和统计信息", "security": [], "responses": { "200": { "description": "服务器正常", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "active_ws": { "type": "integer" }, "keys_total": { "type": "integer" }, "admin_active": { "type": "integer" }, "server_active": { "type": "integer" }, "regular_active": { "type": "integer" } } } } } } } } }, "/manage/keys": { "get": { "summary": "获取所有 API Key", "description": "获取所有 API Key 列表 (仅 Admin)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "创建 API Key", "description": "创建新的 Admin 或 Regular Key (创建 Regular Key 会自动附带一个 Server Key)", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyRequest" } } } }, "responses": { "201": { "description": "创建成功", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyWithSecret" }, { "type": "object", "properties": { "regularKey": { "$ref": "#/components/schemas/ApiKeyWithSecret" }, "serverKey": { "$ref": "#/components/schemas/ApiKeyWithSecret" } } } ] } } } } } } }, "/manage/keys/{key_id}": { "get": { "summary": "获取 API Key 详情", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "404": { "description": "未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "删除 API Key", "description": "仅 Admin 可操作，不能删除自己", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "删除成功" }, "400": { "description": "无法删除（如试图删除自己）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/manage/keys/{key_id}/activate": { "patch": { "summary": "激活 API Key", "description": "Admin 可激活任意 Key，Regular 仅可激活关联的 Server Key", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/manage/keys/{key_id}/deactivate": { "patch": { "summary": "停用 API Key", "description": "Admin 可停用任意 Key，Regular 仅可停用关联的 Server Key", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/manage/keys/server-keys": { "get": { "summary": "获取 Server Key 列表", "description": "Admin 获取所有 Server Key，Regular 获取关联的 Server Key", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "post": { "summary": "创建 Server Key", "description": "为指定的 Regular Key 创建新的 Server Key (仅 Admin，Regular Key 不能为自己创建)", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServerKeyRequest" } } } }, "responses": { "201": { "description": "创建成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWithSecret" } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Regular Key 不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/events": { "post": { "summary": "发送事件", "description": "发送 Minecraft 事件并广播给所有 WebSocket 连接", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "成功广播", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/api/server/info": { "get": { "summary": "获取服务器信息", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "server_id", "schema": { "type": "string" }, "description": "仅 Admin 需要" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "server_id": { "type": "string" }, "status": { "type": "string" }, "online_players": { "type": "integer" } } } } } } } } }, "/api/server/command": { "post": { "summary": "发送服务器命令", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } }, "responses": { "200": { "description": "命令发送成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "description": "禁止的命令", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/ai/config": { "get": { "summary": "获取 AI 配置 (Admin)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiConfig" } } } }, "404": { "description": "配置不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "创建 AI 配置 (Admin)", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiConfigUpdateRequest" } } } }, "responses": { "201": { "description": "创建成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiConfig" } } } } } }, "patch": { "summary": "更新 AI 配置 (Admin)", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiConfigUpdateRequest" } } } }, "responses": { "200": { "description": "更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiConfig" } } } } } }, "delete": { "summary": "删除 AI 配置 (Admin)", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "删除成功" } } } }, "/api/ai/config/test": { "post": { "summary": "测试 AI 连接 (Admin)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "连接成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "model": { "type": "string" }, "response": { "type": "string" } } } } } } } } }, "/api/ai/chat": { "post": { "summary": "AI 聊天", "description": "发送消息给 AI 并获取回复", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChatRequest" } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reply": { "type": "string" }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } } } } }, "403": { "description": "AI 功能已禁用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "AI 配置不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }