zzy
60d6628b0d
feat(bookmark): 添加文件夹树结构导入导出接口
新增 `/bookmarks/v1/folder/serial` 接口，支持文件夹树结构的压缩导出与解压导入。
同时完善了相关响应结构体定义，如 ImportResponse 等。
refactor(bookmark): 重命名配置文件并调整字段命名
将 `config/api.yaml` 重命名为 `config/bookmark.yaml`，并统一将 parent_path_id 字段
更名为 parent_id。此外，更新 API 鉴权头名称为 X-BookMark-Token。
feat(bookmark): 实现文件夹挂载管理功能
新增以下三个接口用于管理文件夹挂载：
- GET `/bookmarks/v1/folder/{id}/mount` 获取挂载信息
- POST `/bookmarks/v1/folder/{id}/mount` 挂载文件夹
- DELETE `/bookmarks/v1/folder/{id}/mount` 取消挂载
新增相关结构体定义：MountResponse、MountInfo。
feat(vfs): 初始化虚拟文件系统 API 配置
新增 `config/vfs.yaml` 和 `config/vfs_cfg.yaml` 配置文件，定义 VFS 相关接口和代码生成规则。
接口包括文件/目录的创建、读取、更新和删除操作，并引入新的安全头 X-VFS-Token。
chore(config): 忽略 data 目录并更新生成路径
.gitignore 中新增忽略 data/ 目录。同时更新 bookmark 和 vfs 的代码生成输出路径分别为
`./gen/bookmarks/gen.go` 和 `./gen/vfs/gen.go`。
chore(deps): 引入 casbin、gopsutil 等依赖库
go.mod 中新增 casbin 权限控制、gopsutil 系统监控等相关依赖。
```
776 lines
20 KiB
YAML
776 lines
20 KiB
YAML
openapi: '3.0.3'
|
|
info:
|
|
title: zzyxyz_api
|
|
description: API服务
|
|
version: '1.0'
|
|
servers:
|
|
- url: http://localhost:8080/api
|
|
description: 开发环境
|
|
- url: https://api.zzyxyz.com/api
|
|
description: 生产环境
|
|
tags:
|
|
- name: folder
|
|
description: 文件夹相关操作
|
|
- name: data
|
|
description: 书签相关操作
|
|
security:
|
|
- ApiKeyAuth: []
|
|
|
|
paths:
|
|
/bookmarks/v1/folder/serial:
|
|
get:
|
|
summary: 导出文件夹树结构
|
|
description: 递归导出整个文件夹树结构并压缩返回
|
|
operationId: exportFolderTree
|
|
tags: [folder]
|
|
responses:
|
|
'200':
|
|
description: 压缩的文件夹树数据
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
post:
|
|
summary: 导入文件夹树结构
|
|
description: 上传并解压文件夹树结构数据，重建文件系统
|
|
operationId: importFolderTree
|
|
tags: [folder]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
responses:
|
|
'200':
|
|
description: 导入成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ImportResponse'
|
|
'400':
|
|
description: 数据格式错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/folder:
|
|
post:
|
|
summary: 创建文件夹
|
|
description: 创建一个存储书签或者文件夹的文件夹
|
|
operationId: createFolder
|
|
tags: [folder]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderRequest'
|
|
responses:
|
|
'201':
|
|
description: 创建成功的文件夹
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderResponse'
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/folder/{id}:
|
|
get:
|
|
summary: 获取文件夹基础信息
|
|
description: 获取文件夹基础信息不包含内容,只有元数据
|
|
operationId: getFolderInfo
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
example: 1
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'200':
|
|
description: 文件夹详情
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderResponse'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
put:
|
|
summary: 更新文件夹
|
|
description: 修改文件夹的元数据(包括修改名称和移动文件夹)
|
|
operationId: updateFolder
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderRequest'
|
|
responses:
|
|
'200':
|
|
description: 更新后的文件夹
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderResponse'
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
delete:
|
|
summary: 删除文件夹
|
|
description: 删除文件夹(文件夹不能有内容)
|
|
operationId: deleteFolder
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'204':
|
|
description: 删除成功
|
|
'400':
|
|
description: 文件夹不为空，无法删除
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/folder/{id}/mount:
|
|
get:
|
|
summary: 获取文件夹挂载信息
|
|
description: 获取指定文件夹的所有挂载信息
|
|
operationId: getFolderMounts
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
description: 文件夹ID
|
|
responses:
|
|
'200':
|
|
description: 挂载信息列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/MountInfo'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
post:
|
|
summary: 挂载文件夹
|
|
description: 将指定文件夹挂载到目标位置
|
|
operationId: mountFolder
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
description: 要挂载的文件夹ID
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
target_folder_id:
|
|
type: integer
|
|
format: int64
|
|
description: 目标文件夹ID(挂载点)
|
|
mount_name:
|
|
type: string
|
|
description: 挂载后的显示名称（可选，默认使用原文件夹名）
|
|
required:
|
|
- target_folder_id
|
|
responses:
|
|
'200':
|
|
description: 挂载成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/MountResponse'
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'409':
|
|
description: 挂载冲突（如循环挂载、重复挂载等）
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
delete:
|
|
summary: 取消挂载文件夹
|
|
description: 取消指定文件夹的挂载关系
|
|
operationId: unmountFolder
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
description: 要取消挂载的文件夹ID
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
mount_point_id:
|
|
type: integer
|
|
format: int64
|
|
description: 挂载点ID(从哪个位置取消挂载)
|
|
required:
|
|
- mount_point_id
|
|
responses:
|
|
'200':
|
|
description: 取消挂载成功
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: 挂载关系不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/folder/{id}/content:
|
|
get:
|
|
summary: 获取文件夹的内容
|
|
description: 只获取当前文件夹的内容,不会递归搜索
|
|
operationId: getFolderContent
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'200':
|
|
description: 文件夹子节点列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FolderContentResponse'
|
|
'404':
|
|
description: 文件夹不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
delete:
|
|
summary: 删除文件夹的内容
|
|
description: 删除文件夹的内容(危险操作)
|
|
operationId: deleteFolderContent
|
|
tags: [folder]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: mode
|
|
in: query
|
|
description: 删除模式
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum: [onlyContent, onlyEmptyFolder, onlyFolder, all]
|
|
responses:
|
|
'200':
|
|
description: 删除成功
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/data:
|
|
post:
|
|
summary: 创建书签
|
|
description: 在文件夹下创建一个书签
|
|
operationId: createBookmark
|
|
tags: [data]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BookmarkRequest'
|
|
responses:
|
|
'201':
|
|
description: 创建成功的书签
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BookmarkResponse'
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/bookmarks/v1/data/{id}:
|
|
get:
|
|
summary: 获取书签详情
|
|
description: 通过id获取书签内容
|
|
operationId: getBookmark
|
|
tags: [data]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'200':
|
|
description: 书签详情
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BookmarkResponse'
|
|
'404':
|
|
description: 书签不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
put:
|
|
summary: 更新书签
|
|
description: 更新指定id的书签
|
|
operationId: updateBookmark
|
|
tags: [data]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BookmarkRequest'
|
|
responses:
|
|
'200':
|
|
description: 更新后的书签
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BookmarkResponse'
|
|
'400':
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: 书签不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
delete:
|
|
summary: 删除书签
|
|
description: 删除指定id的书签
|
|
operationId: deleteBookmark
|
|
tags: [data]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
example: 1
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
responses:
|
|
'204':
|
|
description: 删除成功
|
|
'404':
|
|
description: 书签不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-BookMark-Token
|
|
responses:
|
|
ServerInternalError:
|
|
description: 服务器内部错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
Unauthorized:
|
|
description: 未授权
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
schemas:
|
|
ImportResponse:
|
|
type: object
|
|
properties:
|
|
imported_folders:
|
|
type: integer
|
|
description: 导入的文件夹数量
|
|
imported_bookmarks:
|
|
type: integer
|
|
description: 导入的书签数量
|
|
duration:
|
|
type: string
|
|
description: 导入耗时
|
|
required:
|
|
- imported_folders
|
|
- imported_bookmarks
|
|
- duration
|
|
|
|
MountResponse:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 挂载关系ID
|
|
source_folder_id:
|
|
type: integer
|
|
format: int64
|
|
description: 源文件夹ID
|
|
target_folder_id:
|
|
type: integer
|
|
format: int64
|
|
description: 目标文件夹ID(挂载点)
|
|
mount_name:
|
|
type: string
|
|
description: 挂载显示名称
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: 挂载时间
|
|
required:
|
|
- id
|
|
- source_folder_id
|
|
- target_folder_id
|
|
- mount_name
|
|
- created_at
|
|
|
|
MountInfo:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 挂载关系ID
|
|
source_folder:
|
|
$ref: '#/components/schemas/FolderBriefResponse'
|
|
target_folder:
|
|
$ref: '#/components/schemas/FolderBriefResponse'
|
|
mount_name:
|
|
type: string
|
|
description: 挂载显示名称
|
|
is_mounted_here:
|
|
type: boolean
|
|
description: true表示此文件夹被挂载到target_folder,false表示此文件夹挂载了source_folder
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: 挂载时间
|
|
required:
|
|
- id
|
|
- source_folder
|
|
- target_folder
|
|
- mount_name
|
|
- is_mounted_here
|
|
- created_at
|
|
|
|
FolderRequest:
|
|
description: 文件夹请求结构体
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 255
|
|
description: 文件夹名称
|
|
example: 测试名称
|
|
parent_id:
|
|
type: integer
|
|
format: int64
|
|
description: 父文件夹ID 若为空则自动创建在用户根目录下
|
|
example: null
|
|
required:
|
|
- name
|
|
|
|
BookmarkRequest:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 255
|
|
description: 书签名称
|
|
example: 测试名称
|
|
link:
|
|
type: string
|
|
description: 书签链接
|
|
example: /swagger/index.html
|
|
detail:
|
|
type: string
|
|
description: 书签详情链接
|
|
description:
|
|
type: string
|
|
description: 书签描述
|
|
parent_id:
|
|
type: integer
|
|
format: int64
|
|
description: 父文件夹ID 若为空则自动创建在用户根目录下
|
|
example: null
|
|
required:
|
|
- name
|
|
|
|
FolderResponse:
|
|
type: object
|
|
description: 文件夹响应结构体
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 文件夹ID
|
|
name:
|
|
type: string
|
|
description: 文件夹名称
|
|
parent_id:
|
|
type: integer
|
|
format: int64
|
|
description: 父文件夹ID
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: 创建时间
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: 更新时间
|
|
sub_folder_count:
|
|
type: integer
|
|
description: 子文件夹数量
|
|
bookmark_count:
|
|
type: integer
|
|
description: 书签数量
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- updated_at
|
|
- sub_folder_count
|
|
- bookmark_count
|
|
|
|
BookmarkResponse:
|
|
type: object
|
|
description: 书签相应结构体
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 书签ID
|
|
name:
|
|
type: string
|
|
description: 书签名称
|
|
link:
|
|
type: string
|
|
description: 书签链接
|
|
detail:
|
|
type: string
|
|
description: 书签详情链接
|
|
description:
|
|
type: string
|
|
description: 书签描述
|
|
parent_id:
|
|
type: integer
|
|
format: int64
|
|
description: 父文件夹ID
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: 创建时间
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: 更新时间
|
|
required:
|
|
- id
|
|
- name
|
|
- parent_id
|
|
- created_at
|
|
- updated_at
|
|
|
|
FolderContentResponse:
|
|
type: object
|
|
properties:
|
|
sub_folders:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FolderBriefResponse'
|
|
description: 子文件夹列表
|
|
bookmarks:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/BookmarkBriefResponse'
|
|
description: 书签列表
|
|
required:
|
|
- sub_folders
|
|
- bookmarks
|
|
|
|
FolderBriefResponse:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 文件夹ID
|
|
name:
|
|
type: string
|
|
description: 文件夹名称
|
|
required:
|
|
- id
|
|
- name
|
|
|
|
BookmarkBriefResponse:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: 书签ID
|
|
name:
|
|
type: string
|
|
description: 书签名称
|
|
required:
|
|
- id
|
|
- name
|
|
|
|
Error:
|
|
type: object
|
|
description: 错误信息
|
|
properties:
|
|
errtype:
|
|
type: string
|
|
example: "ParameterError"
|
|
description: 错误类型
|
|
message:
|
|
example: "传递的第一个参数错误"
|
|
type: string
|
|
description: 错误信息
|
|
required:
|
|
- errtype
|
|
- message
|