555 lines
13 KiB
YAML
555 lines
13 KiB
YAML
basePath: /
|
||
definitions:
|
||
admin.CreateTokenRequest:
|
||
properties:
|
||
expire_at:
|
||
type: string
|
||
name:
|
||
example: Test Token
|
||
type: string
|
||
scope:
|
||
example: upload,pickup
|
||
type: string
|
||
required:
|
||
- name
|
||
type: object
|
||
admin.CreateTokenResponse:
|
||
properties:
|
||
data:
|
||
$ref: '#/definitions/model.APIToken'
|
||
token:
|
||
type: string
|
||
type: object
|
||
admin.ListBatchesResponse:
|
||
properties:
|
||
data:
|
||
items:
|
||
$ref: '#/definitions/model.FileBatch'
|
||
type: array
|
||
page:
|
||
type: integer
|
||
page_size:
|
||
type: integer
|
||
total:
|
||
type: integer
|
||
type: object
|
||
admin.LoginRequest:
|
||
properties:
|
||
password:
|
||
example: admin
|
||
type: string
|
||
required:
|
||
- password
|
||
type: object
|
||
admin.LoginResponse:
|
||
properties:
|
||
token:
|
||
type: string
|
||
type: object
|
||
admin.UpdateBatchRequest:
|
||
properties:
|
||
expire_at:
|
||
type: string
|
||
expire_type:
|
||
type: string
|
||
max_downloads:
|
||
type: integer
|
||
remark:
|
||
type: string
|
||
status:
|
||
type: string
|
||
type: object
|
||
model.APIToken:
|
||
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
|
||
type: object
|
||
model.FileBatch:
|
||
properties:
|
||
created_at:
|
||
type: string
|
||
download_count:
|
||
type: integer
|
||
expire_at:
|
||
type: string
|
||
expire_type:
|
||
description: time / download / permanent
|
||
type: string
|
||
file_items:
|
||
items:
|
||
$ref: '#/definitions/model.FileItem'
|
||
type: array
|
||
id:
|
||
type: integer
|
||
max_downloads:
|
||
type: integer
|
||
pickup_code:
|
||
type: string
|
||
remark:
|
||
type: string
|
||
status:
|
||
description: active / expired / deleted
|
||
type: string
|
||
updated_at:
|
||
type: string
|
||
type: object
|
||
model.FileItem:
|
||
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
|
||
type: object
|
||
model.Response:
|
||
properties:
|
||
code:
|
||
example: 200
|
||
type: integer
|
||
data: {}
|
||
msg:
|
||
example: success
|
||
type: string
|
||
type: object
|
||
public.PickupResponse:
|
||
properties:
|
||
download_count:
|
||
type: integer
|
||
expire_at:
|
||
type: string
|
||
expire_type:
|
||
type: string
|
||
files:
|
||
items:
|
||
$ref: '#/definitions/model.FileItem'
|
||
type: array
|
||
max_downloads:
|
||
type: integer
|
||
remark:
|
||
type: string
|
||
type: object
|
||
public.UploadResponse:
|
||
properties:
|
||
batch_id:
|
||
type: integer
|
||
expire_at:
|
||
type: string
|
||
pickup_code:
|
||
type: string
|
||
type: object
|
||
info:
|
||
contact:
|
||
email: support@swagger.io
|
||
name: API Support
|
||
url: http://www.swagger.io/support
|
||
description: 自托管的文件暂存柜后端系统 API 文档
|
||
license:
|
||
name: Apache 2.0
|
||
url: http://www.apache.org/licenses/LICENSE-2.0.html
|
||
termsOfService: http://swagger.io/terms/
|
||
title: 文件暂存柜 API
|
||
version: "1.0"
|
||
paths:
|
||
/admin/api-tokens:
|
||
get:
|
||
description: 获取系统中所有 API Token 的详详信息（不包含哈希）
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
items:
|
||
$ref: '#/definitions/model.APIToken'
|
||
type: array
|
||
type: object
|
||
"401":
|
||
description: Unauthorized
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 获取 API Token 列表
|
||
tags:
|
||
- Admin
|
||
post:
|
||
consumes:
|
||
- application/json
|
||
description: 创建一个新的 API Token，返回原始 Token（仅显示一次）
|
||
parameters:
|
||
- description: Token 信息
|
||
in: body
|
||
name: request
|
||
required: true
|
||
schema:
|
||
$ref: '#/definitions/admin.CreateTokenRequest'
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"201":
|
||
description: Created
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/admin.CreateTokenResponse'
|
||
type: object
|
||
"400":
|
||
description: Bad Request
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 创建 API Token
|
||
tags:
|
||
- Admin
|
||
/admin/api-tokens/{id}:
|
||
delete:
|
||
description: 根据 ID 永久删除 API Token
|
||
parameters:
|
||
- description: Token ID
|
||
in: path
|
||
name: id
|
||
required: true
|
||
type: integer
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
"500":
|
||
description: Internal Server Error
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 删除 API Token
|
||
tags:
|
||
- Admin
|
||
/admin/batch/{batch_id}:
|
||
delete:
|
||
description: 标记批次为已删除，并物理删除关联的存储文件
|
||
parameters:
|
||
- description: 批次 ID
|
||
in: path
|
||
name: batch_id
|
||
required: true
|
||
type: integer
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
"500":
|
||
description: Internal Server Error
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 删除批次
|
||
tags:
|
||
- Admin
|
||
get:
|
||
description: 根据批次 ID 获取批次信息及关联的文件列表
|
||
parameters:
|
||
- description: 批次 ID
|
||
in: path
|
||
name: batch_id
|
||
required: true
|
||
type: integer
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/model.FileBatch'
|
||
type: object
|
||
"404":
|
||
description: Not Found
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 获取批次详情
|
||
tags:
|
||
- Admin
|
||
put:
|
||
consumes:
|
||
- application/json
|
||
description: 允许修改备注、过期策略、最大下载次数、状态等
|
||
parameters:
|
||
- description: 批次 ID
|
||
in: path
|
||
name: batch_id
|
||
required: true
|
||
type: integer
|
||
- description: 修改内容
|
||
in: body
|
||
name: request
|
||
required: true
|
||
schema:
|
||
$ref: '#/definitions/admin.UpdateBatchRequest'
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/model.FileBatch'
|
||
type: object
|
||
"400":
|
||
description: Bad Request
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 修改批次信息
|
||
tags:
|
||
- Admin
|
||
/admin/batches:
|
||
get:
|
||
description: 分页查询所有文件批次，支持按状态过滤和取件码模糊搜索
|
||
parameters:
|
||
- description: 页码 (默认 1)
|
||
in: query
|
||
name: page
|
||
type: integer
|
||
- description: 每页数量 (默认 20)
|
||
in: query
|
||
name: page_size
|
||
type: integer
|
||
- description: 状态 (active/expired/deleted)
|
||
in: query
|
||
name: status
|
||
type: string
|
||
- description: 取件码 (模糊搜索)
|
||
in: query
|
||
name: pickup_code
|
||
type: string
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/admin.ListBatchesResponse'
|
||
type: object
|
||
"401":
|
||
description: Unauthorized
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
security:
|
||
- AdminAuth: []
|
||
summary: 获取批次列表
|
||
tags:
|
||
- Admin
|
||
/admin/login:
|
||
post:
|
||
consumes:
|
||
- application/json
|
||
description: 通过密码换取 JWT Token
|
||
parameters:
|
||
- description: 登录请求
|
||
in: body
|
||
name: request
|
||
required: true
|
||
schema:
|
||
$ref: '#/definitions/admin.LoginRequest'
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/admin.LoginResponse'
|
||
type: object
|
||
"401":
|
||
description: Unauthorized
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
summary: 管理员登录
|
||
tags:
|
||
- Admin
|
||
/api/download/batch/{pickup_code}:
|
||
get:
|
||
description: 根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载
|
||
parameters:
|
||
- description: 取件码
|
||
in: path
|
||
name: pickup_code
|
||
required: true
|
||
type: string
|
||
produces:
|
||
- application/zip
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
type: file
|
||
"404":
|
||
description: Not Found
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
summary: 批量下载文件
|
||
tags:
|
||
- Public
|
||
/api/download/file/{file_id}:
|
||
get:
|
||
description: 根据文件 ID 下载单个文件
|
||
parameters:
|
||
- description: 文件 ID
|
||
in: path
|
||
name: file_id
|
||
required: true
|
||
type: integer
|
||
produces:
|
||
- application/octet-stream
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
type: file
|
||
"404":
|
||
description: Not Found
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
"410":
|
||
description: Gone
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
summary: 下载单个文件
|
||
tags:
|
||
- Public
|
||
/api/pickup/{pickup_code}:
|
||
get:
|
||
description: 根据取件码获取文件批次详详情和文件列表
|
||
parameters:
|
||
- description: 取件码
|
||
in: path
|
||
name: pickup_code
|
||
required: true
|
||
type: string
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/public.PickupResponse'
|
||
type: object
|
||
"404":
|
||
description: Not Found
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
summary: 获取批次信息
|
||
tags:
|
||
- Public
|
||
/api/upload:
|
||
post:
|
||
consumes:
|
||
- multipart/form-data
|
||
description: 上传一个或多个文件并创建一个提取批次
|
||
parameters:
|
||
- description: 文件列表
|
||
in: formData
|
||
name: files
|
||
required: true
|
||
type: file
|
||
- description: 备注
|
||
in: formData
|
||
name: remark
|
||
type: string
|
||
- description: 过期类型 (time/download/permanent)
|
||
in: formData
|
||
name: expire_type
|
||
type: string
|
||
- description: 过期天数 (针对 time 类型)
|
||
in: formData
|
||
name: expire_days
|
||
type: integer
|
||
- description: 最大下载次数 (针对 download 类型)
|
||
in: formData
|
||
name: max_downloads
|
||
type: integer
|
||
produces:
|
||
- application/json
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/definitions/model.Response'
|
||
- properties:
|
||
data:
|
||
$ref: '#/definitions/public.UploadResponse'
|
||
type: object
|
||
"400":
|
||
description: Bad Request
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
"500":
|
||
description: Internal Server Error
|
||
schema:
|
||
$ref: '#/definitions/model.Response'
|
||
summary: 上传文件
|
||
tags:
|
||
- Public
|
||
securityDefinitions:
|
||
AdminAuth:
|
||
description: Type "Bearer <your-jwt-token>" to authenticate.
|
||
in: header
|
||
name: Authorization
|
||
type: apiKey
|
||
swagger: "2.0"
|