FileRelay/docs/swagger.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
  config.APITokenConfig:
    properties:
      allowAdminAPI:
        type: boolean
      enabled:
        type: boolean
      maxTokens:
        type: integer
    type: object
  config.Config:
    properties:
      apitoken:
        $ref: '#/definitions/config.APITokenConfig'
      database:
        $ref: '#/definitions/config.DatabaseConfig'
      security:
        $ref: '#/definitions/config.SecurityConfig'
      site:
        $ref: '#/definitions/config.SiteConfig'
      storage:
        $ref: '#/definitions/config.StorageConfig'
      upload:
        $ref: '#/definitions/config.UploadConfig'
    type: object
  config.DatabaseConfig:
    properties:
      path:
        type: string
    type: object
  config.SecurityConfig:
    properties:
      adminPasswordHash:
        type: string
      jwtsecret:
        type: string
      pickupCodeLength:
        type: integer
      pickupFailLimit:
        type: integer
    type: object
  config.SiteConfig:
    properties:
      description:
        type: string
      name:
        type: string
    type: object
  config.StorageConfig:
    properties:
      local:
        properties:
          path:
            type: string
        type: object
      s3:
        properties:
          accessKey:
            type: string
          bucket:
            type: string
          endpoint:
            type: string
          region:
            type: string
          secretKey:
            type: string
          useSSL:
            type: boolean
        type: object
      type:
        type: string
      webDAV:
        properties:
          password:
            type: string
          root:
            type: string
          url:
            type: string
          username:
            type: string
        type: object
    type: object
  config.UploadConfig:
    properties:
      maxBatchFiles:
        type: integer
      maxFileSizeMB:
        type: integer
      maxRetentionDays:
        type: integer
    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:
      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:
        items:
          $ref: '#/definitions/model.FileItem'
        type: array
      id:
        type: string
      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
    type: object
  model.FileItem:
    properties:
      batch_id:
        type: string
      created_at:
        type: string
      id:
        type: string
      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:
      content:
        type: string
      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:
        type: string
    type: object
  public.PublicConfig:
    properties:
      api_token:
        properties:
          enabled:
            type: boolean
        type: object
      site:
        $ref: '#/definitions/config.SiteConfig'
      upload:
        $ref: '#/definitions/config.UploadConfig'
    type: object
  public.UploadResponse:
    properties:
      batch_id:
        type: string
      expire_at:
        type: string
      pickup_code:
        type: string
    type: object
  public.UploadTextRequest:
    properties:
      content:
        example: 这是一段长文本内容...
        type: string
      expire_days:
        example: 7
        type: integer
      expire_type:
        example: time
        type: string
      max_downloads:
        example: 5
        type: integer
      remark:
        example: 文本备注
        type: string
    required:
    - content
    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/api-tokens/{id}/revoke:
    post:
      description: 将 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/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/batches/{batch_id}:
    delete:
      description: 标记批次为已删除，并物理删除关联的存储文件
      parameters:
      - description: 批次 ID (UUID)
        in: path
        name: batch_id
        required: true
        type: string
      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 (UUID)
        in: path
        name: batch_id
        required: true
        type: string
      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 (UUID)
        in: path
        name: batch_id
        required: true
        type: string
      - 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/config:
    get:
      description: 获取系统的完整配置文件内容（仅管理员）
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/config.Config'
      security:
      - AdminAuth: []
      summary: 获取完整配置
      tags:
      - Admin
    put:
      consumes:
      - application/json
      description: 更新系统的配置文件内容（仅管理员）
      parameters:
      - description: 新配置内容
        in: body
        name: config
        required: true
        schema:
          $ref: '#/definitions/config.Config'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Response'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.Response'
        "500":
          description: Internal Server Error
          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/batches:
    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
  /api/batches/{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/batches/{pickup_code}/download:
    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/batches/text:
    post:
      consumes:
      - application/json
      description: 中转一段长文本内容并创建一个提取批次
      parameters:
      - description: 文本内容及配置
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/public.UploadTextRequest'
      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
  /api/config:
    get:
      description: 获取前端展示所需的非敏感配置数据
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/public.PublicConfig'
              type: object
      summary: 获取公共配置
      tags:
      - Public
  /api/files/{file_id}/download:
    get:
      description: 根据文件 ID 下载单个文件
      parameters:
      - description: 文件 ID (UUID)
        in: path
        name: file_id
        required: true
        type: string
      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
securityDefinitions:
  AdminAuth:
    description: Type "Bearer <your-jwt-token>" to authenticate.
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"