{ "openapi": "3.1.0", "info": { "title": "KaoPeiLian SQL Executor API", "description": "SQL 执行器 API，专门为 Dify 平台集成设计，支持对考陪练系统数据库执行查询和写入操作。\n\n## 主要功能\n- 执行 SQL 查询和写入操作\n- 支持参数化查询防止 SQL 注入\n- 获取数据库表列表和表结构\n- SQL 语句验证\n\n## 安全说明\n所有接口都需要 JWT Bearer Token 认证。请先通过登录接口获取访问令牌。", "version": "1.0.0", "contact": { "name": "KaoPeiLian Tech Support", "email": "support@kaopeilian.com" } }, "servers": [ { "url": "http://120.79.247.16:8000/api/v1", "description": "考陪练系统服务器" }, { "url": "http://aiedu.ireborn.com.cn/api/v1", "description": "域名访问" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/auth/login": { "post": { "tags": ["认证"], "summary": "用户登录", "description": "获取访问令牌，用于后续 API 调用", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "examples": { "admin": { "summary": "管理员登录", "value": { "username": "admin", "password": "admin123" } } } } } }, "responses": { "200": { "description": "登录成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "description": "用户名或密码错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sql/execute": { "post": { "tags": ["SQL执行器"], "summary": "执行 SQL 语句", "description": "执行查询或写入 SQL 语句。\n\n**查询操作**: SELECT, SHOW, DESCRIBE\n**写入操作**: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP\n\n支持参数化查询，使用 `:param_name` 格式定义参数。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlExecuteRequest" }, "examples": { "simpleQuery": { "summary": "简单查询", "value": { "sql": "SELECT id, username, role FROM users LIMIT 5" } }, "parameterizedQuery": { "summary": "参数化查询", "value": { "sql": "SELECT * FROM courses WHERE category = :category AND status = :status", "params": { "category": "护肤", "status": "active" } } }, "insertData": { "summary": "插入数据", "value": { "sql": "INSERT INTO knowledge_points (title, content, course_id) VALUES (:title, :content, :course_id)", "params": { "title": "面部护理基础", "content": "面部护理的基本步骤...", "course_id": 1 } } } } } } }, "responses": { "200": { "description": "SQL 执行成功", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QueryResponse" }, { "$ref": "#/components/schemas/ExecuteResponse" } ] }, "examples": { "queryResult": { "summary": "查询结果", "value": { "code": 200, "message": "SQL 执行成功", "data": { "type": "query", "columns": ["id", "username", "role"], "rows": [ { "id": 1, "username": "admin", "role": "admin" }, { "id": 2, "username": "user1", "role": "trainee" } ], "row_count": 2 } } }, "executeResult": { "summary": "写入结果", "value": { "code": 200, "message": "SQL 执行成功", "data": { "type": "execute", "affected_rows": 1, "success": true } } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未认证或认证失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "SQL 执行错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sql/validate": { "post": { "tags": ["SQL执行器"], "summary": "验证 SQL 语法", "description": "验证 SQL 语句的语法正确性，不执行实际操作", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlValidateRequest" } } } }, "responses": { "200": { "description": "验证完成", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } } } } }, "/sql/tables": { "get": { "tags": ["SQL执行器"], "summary": "获取表列表", "description": "获取数据库中所有表的列表", "responses": { "200": { "description": "成功获取表列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TablesResponse" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sql/table/{table_name}/schema": { "get": { "tags": ["SQL执行器"], "summary": "获取表结构", "description": "获取指定表的结构信息，包括字段名、类型、约束等", "parameters": [ { "name": "table_name", "in": "path", "required": true, "description": "表名", "schema": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "example": "users" } ], "responses": { "200": { "description": "成功获取表结构", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSchemaResponse" } } } }, "400": { "description": "无效的表名", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "使用登录接口返回的 access_token。\n格式: Bearer {access_token}" } }, "schemas": { "LoginRequest": { "type": "object", "required": ["username", "password"], "properties": { "username": { "type": "string", "description": "用户名", "example": "admin" }, "password": { "type": "string", "format": "password", "description": "密码", "example": "admin123" } } }, "LoginResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "登录成功" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "username": { "type": "string", "example": "admin" }, "role": { "type": "string", "example": "admin" } } }, "token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT 访问令牌", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "description": "过期时间（秒）", "example": 1800 } } } } } } }, "SqlExecuteRequest": { "type": "object", "required": ["sql"], "properties": { "sql": { "type": "string", "description": "要执行的 SQL 语句", "example": "SELECT * FROM users WHERE role = :role" }, "params": { "type": "object", "description": "SQL 参数字典，键为参数名，值为参数值", "additionalProperties": true, "example": { "role": "admin" } } } }, "SqlValidateRequest": { "type": "object", "required": ["sql"], "properties": { "sql": { "type": "string", "description": "要验证的 SQL 语句", "example": "SELECT * FROM users" } } }, "QueryResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "SQL 执行成功" }, "data": { "type": "object", "properties": { "type": { "type": "string", "enum": ["query"], "example": "query" }, "columns": { "type": "array", "items": { "type": "string" }, "description": "列名数组", "example": ["id", "username", "role"] }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "查询结果行" }, "row_count": { "type": "integer", "description": "返回的行数", "example": 5 } } } } }, "ExecuteResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "SQL 执行成功" }, "data": { "type": "object", "properties": { "type": { "type": "string", "enum": ["execute"], "example": "execute" }, "affected_rows": { "type": "integer", "description": "影响的行数", "example": 1 }, "success": { "type": "boolean", "example": true } } } } }, "ValidateResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "SQL 验证完成" }, "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "SQL 是否有效", "example": true }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "警告信息列表", "example": ["包含危险操作: DROP"] }, "sql_type": { "type": "string", "description": "SQL 类型", "example": "SELECT" } } } } }, "TablesResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "获取表列表成功" }, "data": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string" }, "description": "表名列表", "example": ["users", "courses", "exams"] }, "count": { "type": "integer", "description": "表的数量", "example": 20 } } } } }, "TableSchemaResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "获取表结构成功" }, "data": { "type": "object", "properties": { "table_name": { "type": "string", "example": "users" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "字段名", "example": "id" }, "type": { "type": "string", "description": "字段类型", "example": "int(11)" }, "null": { "type": "string", "enum": ["YES", "NO"], "description": "是否可为空", "example": "NO" }, "key": { "type": "string", "description": "键类型（PRI, UNI, MUL）", "example": "PRI" }, "default": { "type": "string", "nullable": true, "description": "默认值", "example": null }, "extra": { "type": "string", "description": "额外信息", "example": "auto_increment" } } } }, "column_count": { "type": "integer", "description": "列的数量", "example": 10 } } } } }, "ErrorResponse": { "type": "object", "properties": { "detail": { "type": "string", "description": "错误详情", "example": "SQL 执行失败: You have an error in your SQL syntax" } } } } }, "tags": [ { "name": "认证", "description": "用户认证相关接口" }, { "name": "SQL执行器", "description": "SQL 执行和管理相关接口" } ] }