```
feat(api): 初始化项目基础结构与API定义 新增 `.gitignore` 文件，忽略编译输出、生成代码及数据库文件。 新增 `README.md`，包含 Gin 框架和 Swagger 工具的安装与使用说明。 新增 `config/api.yaml`，定义 bookmarks 相关的文件夹与书签操作的 OpenAPI 3.0 接口规范。 新增 `config/cfg.yaml`，配置 oapi-codegen 工具生成 Gin 服务和模型代码。 新增 `go.mod` 和 `go.sum` 文件，初始化 Go 模块并引入 Gin、GORM、SQLite 及 oapi-codegen 等依赖。 ```
This commit is contained in:
523
config/api.yaml
Normal file
523
config/api.yaml
Normal file
@ -0,0 +1,523 @@
|
||||
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:
|
||||
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}/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-API-Key
|
||||
responses:
|
||||
ServerInternalError:
|
||||
description: 服务器内部错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
Unauthorized:
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
schemas:
|
||||
FolderRequest:
|
||||
description: 文件夹请求结构体
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 255
|
||||
description: 文件夹名称
|
||||
example: 测试名称
|
||||
parent_path_id:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 父文件夹ID 若为空则自动创建在用户根目录下
|
||||
example: 1
|
||||
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_path_id:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 父文件夹ID 若为空则自动创建在用户根目录下
|
||||
example: 1
|
||||
required:
|
||||
- name
|
||||
|
||||
FolderResponse:
|
||||
type: object
|
||||
description: 文件夹响应结构体
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 文件夹ID
|
||||
name:
|
||||
type: string
|
||||
description: 文件夹名称
|
||||
parent_path_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
|
||||
- parent_path_id
|
||||
- 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_path_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_path_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
|
||||
Reference in New Issue
Block a user