zzy
b2cc27b8f5
将 bookmark 和 user_np 服务的生成配置分离为 server 和 client 包， 并更新了相应的导入路径。同时更新了 OpenAPI 配置文件中的包名、输出路径及 启用 strict-server 模式以增强类型安全。 此外，同步更新了 VFS 服务的客户端和服务端生成配置，并完善了其 OpenAPI 错误响应定义与二进制内容支持，增强了 API 的规范性和健壮性。 修复了部分权限校验逻辑，并调整了中间件注册方式以适配新的严格模式接口。
355 lines
9.8 KiB
YAML
355 lines
9.8 KiB
YAML
openapi: '3.0.3'
|
|
info:
|
|
title: zzyxyz_vfs_api
|
|
description: 虚拟文件系统API服务
|
|
version: '1.0'
|
|
servers:
|
|
- url: http://localhost:8080/api
|
|
description: 开发环境
|
|
- url: https://api.zzyxyz.com/api
|
|
description: 生产环境
|
|
tags:
|
|
- name: vfs
|
|
description: 虚拟文件系统相关操作
|
|
- name: user
|
|
description: 用户相关操作
|
|
security:
|
|
- ApiKeyAuth: []
|
|
|
|
paths:
|
|
/vfs/v1/users/{username}:
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
example: user
|
|
required: true
|
|
schema:
|
|
type: string
|
|
|
|
post:
|
|
summary: 创建用户
|
|
description: 创建一个用户
|
|
operationId: createUser
|
|
tags: [user]
|
|
responses:
|
|
'201':
|
|
description: 创建成功
|
|
headers:
|
|
X-VFS-Token:
|
|
schema:
|
|
type: string
|
|
description: 认证令牌
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
delete:
|
|
summary: 删除用户
|
|
description: 删除一个用户
|
|
operationId: deleteUser
|
|
tags: [user]
|
|
responses:
|
|
'204':
|
|
description: 删除成功
|
|
'404':
|
|
description: 用户不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
/vfs/v1/files:
|
|
parameters:
|
|
- name: path
|
|
in: query
|
|
required: true
|
|
description: 文件系统路径，例如 "documents/readme.txt" 或 "services/mysql.service" 或 "folder/"
|
|
schema:
|
|
type: string
|
|
example: "readme.txt"
|
|
|
|
get:
|
|
summary: 读取文件或列出目录
|
|
description: 获取指定路径的文件内容或目录列表
|
|
operationId: getVFSNode
|
|
tags: [vfs]
|
|
parameters:
|
|
- name: op
|
|
in: query
|
|
required: false
|
|
description: 操作类型, list表示列出目录内容, 不指定则读取文件内容
|
|
schema:
|
|
type: string
|
|
enum: [list]
|
|
responses:
|
|
'200':
|
|
description: 文件内容或目录列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: 目录条目列表
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VFSDirectoryEntry'
|
|
application/octet-stream:
|
|
schema:
|
|
description: 文件或服务的二进制内容
|
|
type: string
|
|
format: binary
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'404':
|
|
$ref: '#/components/responses/PathNotFoundError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
post:
|
|
summary: 创建文件或目录
|
|
description: 创建文件或目录
|
|
operationId: createVFSNode
|
|
tags: [vfs]
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
description: 文件或服务的二进制内容
|
|
type: string
|
|
format: byte
|
|
responses:
|
|
'201':
|
|
description: 创建成功
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
description: 文件或服务的二进制内容
|
|
type: string
|
|
format: byte
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VFSNodeResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'404':
|
|
$ref: '#/components/responses/PathNotFoundError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
patch:
|
|
summary: 修改文件或修改目录
|
|
description: 修改/移动/重命名/复制 已存在的 文件/目录
|
|
operationId: updateVFSNode
|
|
tags: [vfs]
|
|
parameters:
|
|
- name: op
|
|
in: query
|
|
description: 操作模式
|
|
required: true
|
|
schema:
|
|
type: string
|
|
enum: [move, rename, change, copy]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
description: 目的文件夹路径 / 文件名路径
|
|
example: "/home/"
|
|
responses:
|
|
'200':
|
|
description: 操作成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VFSNodeResponse'
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'404':
|
|
$ref: '#/components/responses/PathNotFoundError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
delete:
|
|
summary: 删除文件或目录
|
|
description: 删除指定路径的文件或目录
|
|
operationId: deleteVFSNode
|
|
tags: [vfs]
|
|
responses:
|
|
'204':
|
|
description: 删除成功
|
|
'400':
|
|
$ref: '#/components/responses/ParameterError'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenError'
|
|
'404':
|
|
$ref: '#/components/responses/PathNotFoundError'
|
|
'500':
|
|
$ref: '#/components/responses/ServerInternalError'
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-VFS-Token
|
|
|
|
responses:
|
|
ServerInternalError:
|
|
description: 服务器内部错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
errtype: "InternalServerError"
|
|
message: "服务器内部错误"
|
|
|
|
UnauthorizedError:
|
|
description: 未授权
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
errtype: "Unauthorized"
|
|
message: "访问被拒绝，缺少有效的认证令牌"
|
|
|
|
ForbiddenError:
|
|
description: 禁止
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
errtype: "Forbidden"
|
|
message: "访问被拒绝，您没有权限访问此资源"
|
|
|
|
PathNotFoundError:
|
|
description: 路径不存在
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
errtype: "PathNotFound"
|
|
message: "指定的路径不存在"
|
|
|
|
ParameterError:
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
errtype: "ParameterError"
|
|
message: "请求参数无效或缺失"
|
|
|
|
schemas:
|
|
VFSNodeType:
|
|
type: string
|
|
description: 节点类型
|
|
enum: [file, directory, service]
|
|
|
|
VFSNodeResponse:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: 节点名称
|
|
type:
|
|
$ref: '#/components/schemas/VFSNodeType'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: 创建时间
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: 更新时间
|
|
required:
|
|
- name
|
|
- type
|
|
- created_at
|
|
- updated_at
|
|
|
|
VFSDirectoryEntry:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: 条目名称
|
|
type:
|
|
$ref: '#/components/schemas/VFSNodeType'
|
|
permissions:
|
|
type: string
|
|
description: 权限信息，如 "rw"
|
|
required:
|
|
- name
|
|
- type
|
|
- modified
|
|
|
|
Error:
|
|
type: object
|
|
description: 错误信息
|
|
properties:
|
|
errtype:
|
|
type: string
|
|
description: |
|
|
错误类型，可能的值包括：
|
|
- "InternalServerError": 服务器内部错误
|
|
- "Unauthorized": 客户端需要提供正确格式权限
|
|
- "Forbidden": 无权限访问
|
|
- "PathNotFound": 路径不存在
|
|
- "ParameterError": 请求参数错误
|
|
- "ConflictError": 资源冲突
|
|
- "DatabaseError": 数据库操作错误
|
|
- "NotFoundError": 资源未找到
|
|
- "AccessDenied": 访问被拒绝
|
|
- "ServiceProxyError": 代理服务错误
|
|
example: "InternalServerError"
|
|
enum:
|
|
- "InternalServerError"
|
|
- "Unauthorized"
|
|
- "Forbidden"
|
|
- "PathNotFound"
|
|
- "ParameterError"
|
|
- "ConflictError"
|
|
- "DatabaseError"
|
|
- "NotFoundError"
|
|
- "AccessDenied"
|
|
- "ServiceProxyError"
|
|
message:
|
|
type: string
|
|
description: 详细的错误信息
|
|
example: "传递的第一个参数错误"
|
|
required:
|
|
- errtype
|
|
- message |