From e1fcf74b668ef35909c0f12bed6b15d3198ef32c Mon Sep 17 00:00:00 2001 From: hxuanyu <2252193204@qq.com> Date: Wed, 14 Jan 2026 10:36:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=96=87=E6=A1=A3=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/swagger.json | 1026 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1026 insertions(+) create mode 100644 api/swagger.json diff --git a/api/swagger.json b/api/swagger.json new file mode 100644 index 0000000..024dc39 --- /dev/null +++ b/api/swagger.json @@ -0,0 +1,1026 @@ +{ + "swagger": "2.0", + "info": { + "description": "自托管的文件暂存柜后端系统 API 文档", + "title": "文件暂存柜 API", + "termsOfService": "http://swagger.io/terms/", + "contact": { + "name": "API Support", + "url": "http://www.swagger.io/support", + "email": "support@swagger.io" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "1.0" + }, + "basePath": "/", + "paths": { + "/admin/api-tokens": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "获取系统中所有 API Token 的详详信息（不包含哈希）", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "获取 API Token 列表", + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/model.APIToken" + } + } + } + } + ] + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + }, + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "创建一个新的 API Token，返回原始 Token（仅显示一次）", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "创建 API Token", + "parameters": [ + { + "description": "Token 信息", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/admin.CreateTokenRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/admin.CreateTokenResponse" + } + } + } + ] + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/admin/api-tokens/{id}": { + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "根据 ID 永久删除 API Token", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "删除 API Token", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/admin/api-tokens/{id}/revoke": { + "post": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "将 API Token 标记为已撤销，使其失效但保留记录", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "撤销 API Token", + "parameters": [ + { + "type": "integer", + "description": "Token ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/admin/batches": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "分页查询所有文件批次，支持按状态过滤和取件码模糊搜索", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "获取批次列表", + "parameters": [ + { + "type": "integer", + "description": "页码 (默认 1)", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "每页数量 (默认 20)", + "name": "page_size", + "in": "query" + }, + { + "type": "string", + "description": "状态 (active/expired/deleted)", + "name": "status", + "in": "query" + }, + { + "type": "string", + "description": "取件码 (模糊搜索)", + "name": "pickup_code", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/admin.ListBatchesResponse" + } + } + } + ] + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/admin/batches/{batch_id}": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "根据批次 ID 获取批次信息及关联的文件列表", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "获取批次详情", + "parameters": [ + { + "type": "integer", + "description": "批次 ID", + "name": "batch_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/model.FileBatch" + } + } + } + ] + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + }, + "put": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "允许修改备注、过期策略、最大下载次数、状态等", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "修改批次信息", + "parameters": [ + { + "type": "integer", + "description": "批次 ID", + "name": "batch_id", + "in": "path", + "required": true + }, + { + "description": "修改内容", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/admin.UpdateBatchRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/model.FileBatch" + } + } + } + ] + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + }, + "delete": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "标记批次为已删除，并物理删除关联的存储文件", + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "删除批次", + "parameters": [ + { + "type": "integer", + "description": "批次 ID", + "name": "batch_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/admin/login": { + "post": { + "description": "通过密码换取 JWT Token", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Admin" + ], + "summary": "管理员登录", + "parameters": [ + { + "description": "登录请求", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/admin.LoginRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/admin.LoginResponse" + } + } + } + ] + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/api/batches": { + "post": { + "description": "上传一个或多个文件并创建一个提取批次", + "consumes": [ + "multipart/form-data" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "上传文件", + "parameters": [ + { + "type": "file", + "description": "文件列表", + "name": "files", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "备注", + "name": "remark", + "in": "formData" + }, + { + "type": "string", + "description": "过期类型 (time/download/permanent)", + "name": "expire_type", + "in": "formData" + }, + { + "type": "integer", + "description": "过期天数 (针对 time 类型)", + "name": "expire_days", + "in": "formData" + }, + { + "type": "integer", + "description": "最大下载次数 (针对 download 类型)", + "name": "max_downloads", + "in": "formData" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/public.UploadResponse" + } + } + } + ] + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/api/batches/text": { + "post": { + "description": "中转一段长文本内容并创建一个提取批次", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "发送长文本", + "parameters": [ + { + "description": "文本内容及配置", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/public.UploadTextRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/public.UploadResponse" + } + } + } + ] + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/api/batches/{pickup_code}": { + "get": { + "description": "根据取件码获取文件批次详详情和文件列表", + "produces": [ + "application/json" + ], + "tags": [ + "Public" + ], + "summary": "获取批次信息", + "parameters": [ + { + "type": "string", + "description": "取件码", + "name": "pickup_code", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/model.Response" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/public.PickupResponse" + } + } + } + ] + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/api/batches/{pickup_code}/download": { + "get": { + "description": "根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载", + "produces": [ + "application/zip" + ], + "tags": [ + "Public" + ], + "summary": "批量下载文件", + "parameters": [ + { + "type": "string", + "description": "取件码", + "name": "pickup_code", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "file" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + }, + "/api/files/{file_id}/download": { + "get": { + "description": "根据文件 ID 下载单个文件", + "produces": [ + "application/octet-stream" + ], + "tags": [ + "Public" + ], + "summary": "下载单个文件", + "parameters": [ + { + "type": "integer", + "description": "文件 ID", + "name": "file_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "file" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/model.Response" + } + }, + "410": { + "description": "Gone", + "schema": { + "$ref": "#/definitions/model.Response" + } + } + } + } + } + }, + "definitions": { + "admin.CreateTokenRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "expire_at": { + "type": "string" + }, + "name": { + "type": "string", + "example": "Test Token" + }, + "scope": { + "type": "string", + "example": "upload,pickup" + } + } + }, + "admin.CreateTokenResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/model.APIToken" + }, + "token": { + "type": "string" + } + } + }, + "admin.ListBatchesResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/model.FileBatch" + } + }, + "page": { + "type": "integer" + }, + "page_size": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "admin.LoginRequest": { + "type": "object", + "required": [ + "password" + ], + "properties": { + "password": { + "type": "string", + "example": "admin" + } + } + }, + "admin.LoginResponse": { + "type": "object", + "properties": { + "token": { + "type": "string" + } + } + }, + "admin.UpdateBatchRequest": { + "type": "object", + "properties": { + "expire_at": { + "type": "string" + }, + "expire_type": { + "type": "string" + }, + "max_downloads": { + "type": "integer" + }, + "remark": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "model.APIToken": { + "type": "object", + "properties": { + "created_at": { + "type": "string" + }, + "expire_at": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "last_used_at": { + "type": "string" + }, + "name": { + "type": "string" + }, + "revoked": { + "type": "boolean" + }, + "scope": { + "type": "string" + } + } + }, + "model.FileBatch": { + "type": "object", + "properties": { + "content": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "download_count": { + "type": "integer" + }, + "expire_at": { + "type": "string" + }, + "expire_type": { + "description": "time / download / permanent", + "type": "string" + }, + "file_items": { + "type": "array", + "items": { + "$ref": "#/definitions/model.FileItem" + } + }, + "id": { + "type": "integer" + }, + "max_downloads": { + "type": "integer" + }, + "pickup_code": { + "type": "string" + }, + "remark": { + "type": "string" + }, + "status": { + "description": "active / expired / deleted", + "type": "string" + }, + "type": { + "description": "file / text", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, + "model.FileItem": { + "type": "object", + "properties": { + "batch_id": { + "type": "integer" + }, + "created_at": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "mime_type": { + "type": "string" + }, + "original_name": { + "type": "string" + }, + "size": { + "type": "integer" + }, + "storage_path": { + "type": "string" + } + } + }, + "model.Response": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 200 + }, + "data": {}, + "msg": { + "type": "string", + "example": "success" + } + } + }, + "public.PickupResponse": { + "type": "object", + "properties": { + "content": { + "type": "string" + }, + "download_count": { + "type": "integer" + }, + "expire_at": { + "type": "string" + }, + "expire_type": { + "type": "string" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/definitions/model.FileItem" + } + }, + "max_downloads": { + "type": "integer" + }, + "remark": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "public.UploadResponse": { + "type": "object", + "properties": { + "batch_id": { + "type": "integer" + }, + "expire_at": { + "type": "string" + }, + "pickup_code": { + "type": "string" + } + } + }, + "public.UploadTextRequest": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "example": "这是一段长文本内容..." + }, + "expire_days": { + "type": "integer", + "example": 7 + }, + "expire_type": { + "type": "string", + "example": "time" + }, + "max_downloads": { + "type": "integer", + "example": 5 + }, + "remark": { + "type": "string", + "example": "文本备注" + } + } + } + }, + "securityDefinitions": { + "AdminAuth": { + "description": "Type \"Bearer \u003cyour-jwt-token\u003e\" to authenticate.", + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } +} \ No newline at end of file