feat: MarkBase initial version
Phase 1 (Infrastructure): - Docs: README.md, AGENTS.md, CHANGELOG.md - Tests: 26 tests (modes_test, filetree_api_test) - Examples: examples/sample.md, sample.json - CI/CD: .gitea/workflows/test.yml, release.yml - Runner: configuration scripts and guides Phase 2 (Quality): - Code quality: rustfmt/clippy config - Security: environment variables - Test coverage: 62 tests (+36) - Documentation: CONTRIBUTING.md, docs/api.yaml - Showcase: demo_features.md, developer_quickstart.md Test coverage: 75% Test pass rate: 100%
This commit is contained in:
Warren
753
docs/api.yaml
Normal file
753
docs/api.yaml
Normal file
@@ -0,0 +1,753 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: MarkBase API
|
||||
description: Momentry Display Engine - Markdown渲染與檔案樹管理系統
|
||||
version: 0.1.0
|
||||
contact:
|
||||
name: MarkBase Team
|
||||
|
||||
servers:
|
||||
- url: http://localhost:11438
|
||||
description: 本地開發伺服器
|
||||
- url: https://gitea.momentry.ddns.net
|
||||
description: 生產伺服器
|
||||
|
||||
tags:
|
||||
- name: Display
|
||||
description: 內容顯示與渲染
|
||||
- name: File Tree
|
||||
description: 檔案樹管理
|
||||
- name: Files
|
||||
description: 檔案操作
|
||||
- name: System
|
||||
description: 系統狀態與控制
|
||||
- name: Audio
|
||||
description: macOS音訊控制
|
||||
|
||||
paths:
|
||||
# Display相關路由
|
||||
/:
|
||||
get:
|
||||
tags: [Display]
|
||||
summary: 主頁顯示
|
||||
description: 返回當前顯示的HTML內容
|
||||
responses:
|
||||
'200':
|
||||
description: HTML內容
|
||||
content:
|
||||
text/html:
|
||||
schema:
|
||||
type: string
|
||||
|
||||
/display:
|
||||
post:
|
||||
tags: [Display]
|
||||
summary: 更新顯示內容
|
||||
description: 根據內容類型更新顯示內容
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [md, markdown, json, url, video, image, html]
|
||||
description: 內容類型
|
||||
data:
|
||||
type: string
|
||||
description: 內容資料
|
||||
file:
|
||||
type: string
|
||||
description:檔案路徑
|
||||
url:
|
||||
type: string
|
||||
description: URL地址
|
||||
html:
|
||||
type: string
|
||||
description: HTML內容
|
||||
step_id:
|
||||
type: string
|
||||
step_num:
|
||||
type: integer
|
||||
step_total:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: 更新成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
/version:
|
||||
get:
|
||||
tags: [System]
|
||||
summary: 取得版本號
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
v:
|
||||
type: integer
|
||||
|
||||
/status:
|
||||
get:
|
||||
tags: [System]
|
||||
summary: 取得狀態
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
paused:
|
||||
type: boolean
|
||||
step:
|
||||
type: integer
|
||||
total:
|
||||
type: integer
|
||||
id:
|
||||
type: string
|
||||
label:
|
||||
type: string
|
||||
voice:
|
||||
type: string
|
||||
|
||||
/body:
|
||||
get:
|
||||
tags: [Display]
|
||||
summary: 取得內容body
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
text/html:
|
||||
schema:
|
||||
type: string
|
||||
|
||||
/labels:
|
||||
get:
|
||||
tags: [System]
|
||||
summary: 取得標籤列表
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
post:
|
||||
tags: [System]
|
||||
summary:更新標籤列表
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
# Audio相關路由
|
||||
/devices:
|
||||
get:
|
||||
tags: [Audio]
|
||||
summary: 取得音訊裝置
|
||||
description: 列出所有音訊輸入/輸出裝置（macOS）
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
output:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
input:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
current_out:
|
||||
type: string
|
||||
current_in:
|
||||
type: string
|
||||
|
||||
/volume:
|
||||
get:
|
||||
tags: [Audio]
|
||||
summary: 取得音量
|
||||
description: 取得當前音量級別（macOS）
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
level:
|
||||
type: integer
|
||||
|
||||
# Command相關路由
|
||||
/command:
|
||||
get:
|
||||
tags: [System]
|
||||
summary: 取得指令隊列
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
cmd:
|
||||
type: string
|
||||
val:
|
||||
type: string
|
||||
post:
|
||||
tags: [System]
|
||||
summary: 提交指令
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
cmd:
|
||||
type: string
|
||||
val:
|
||||
type: string
|
||||
out:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
# File Tree相關路由
|
||||
/api/v2/tree/{user_id}:
|
||||
get:
|
||||
tags: [File Tree]
|
||||
summary: 取得檔案樹
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: mode
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum: [tree, list, grid_sm, grid_lg]
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
mode:
|
||||
type: string
|
||||
nodes:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/FileNode'
|
||||
delete:
|
||||
tags: [File Tree]
|
||||
summary: 刪除所有節點
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
deleted:
|
||||
type: integer
|
||||
|
||||
/api/v2/tree/{user_id}/node:
|
||||
post:
|
||||
tags: [File Tree]
|
||||
summary: 建立節點
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateNodeRequest'
|
||||
responses:
|
||||
'201':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
node_id:
|
||||
type: string
|
||||
|
||||
/api/v2/tree/{user_id}/node/{node_id}:
|
||||
put:
|
||||
tags: [File Tree]
|
||||
summary: 更新節點
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
- name: node_id
|
||||
in: path
|
||||
required: true
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateNodeRequest'
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
delete:
|
||||
tags: [File Tree]
|
||||
summary: 刪除節點
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
- name: node_id
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
/api/v2/tree/{user_id}/node/{node_id}/move:
|
||||
put:
|
||||
tags: [File Tree]
|
||||
summary: 移動節點
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
- name: node_id
|
||||
in: path
|
||||
required: true
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
parent_id:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
/api/v2/tree/{user_id}/node/{node_id}/alias:
|
||||
patch:
|
||||
tags: [File Tree]
|
||||
summary: 更新別名
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
- name: node_id
|
||||
in: path
|
||||
required: true
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
lang:
|
||||
type: string
|
||||
value:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
/api/v2/tree/{user_id}/restore:
|
||||
post:
|
||||
tags: [File Tree]
|
||||
summary: 從外部API恢復檔案樹
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
deleted:
|
||||
type: integer
|
||||
imported:
|
||||
type: integer
|
||||
|
||||
/api/v2/modes:
|
||||
get:
|
||||
tags: [File Tree]
|
||||
summary: 取得顯示模式列表
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
modes:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/DisplayMode'
|
||||
|
||||
# Files相關路由
|
||||
/api/v2/dupes/{user_id}:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 取得重複檔案
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
|
||||
/api/v2/unregister/{file_uuid}:
|
||||
post:
|
||||
tags: [Files]
|
||||
summary: 取消註冊檔案
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
|
||||
/api/v2/upload/{user_id}:
|
||||
post:
|
||||
tags: [Files]
|
||||
summary: 上傳檔案
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
'201':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
filename:
|
||||
type: string
|
||||
file_uuid:
|
||||
type: string
|
||||
sha256:
|
||||
type: string
|
||||
size:
|
||||
type: integer
|
||||
|
||||
/api/v2/render/{file_uuid}:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 渲染檔案
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
text/html:
|
||||
schema:
|
||||
type: string
|
||||
|
||||
/api/v2/render/{file_uuid}/body:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 取得檔案渲染內容
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
text/html:
|
||||
schema:
|
||||
type: string
|
||||
|
||||
/api/v2/files/{file_uuid}/info:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 取得檔案資訊
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FileInfo'
|
||||
|
||||
/api/v2/files/{file_uuid}/probe:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 取得檔案探測資訊
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
|
||||
/api/v2/files/{file_uuid}/stream:
|
||||
get:
|
||||
tags: [Files]
|
||||
summary: 串流檔案
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/octet-stream:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
|
||||
/api/v2/files/{file_uuid}/locations:
|
||||
post:
|
||||
tags: [Files]
|
||||
summary: 新增檔案位置
|
||||
parameters:
|
||||
- name: file_uuid
|
||||
in: path
|
||||
required: true
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
location:
|
||||
type: string
|
||||
label:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
|
||||
components:
|
||||
schemas:
|
||||
FileNode:
|
||||
type: object
|
||||
properties:
|
||||
node_id:
|
||||
type: string
|
||||
label:
|
||||
type: string
|
||||
aliases:
|
||||
type: object
|
||||
file_uuid:
|
||||
type: string
|
||||
sha256:
|
||||
type: string
|
||||
parent_id:
|
||||
type: string
|
||||
node_type:
|
||||
type: string
|
||||
enum: [folder, file]
|
||||
icon:
|
||||
type: string
|
||||
color:
|
||||
type: string
|
||||
bg_color:
|
||||
type: string
|
||||
file_size:
|
||||
type: integer
|
||||
registered_at:
|
||||
type: string
|
||||
children:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
||||
CreateNodeRequest:
|
||||
type: object
|
||||
required: [label]
|
||||
properties:
|
||||
label:
|
||||
type: string
|
||||
node_type:
|
||||
type: string
|
||||
enum: [folder, file]
|
||||
parent_id:
|
||||
type: string
|
||||
file_uuid:
|
||||
type: string
|
||||
sha256:
|
||||
type: string
|
||||
file_size:
|
||||
type: integer
|
||||
file_type:
|
||||
type: string
|
||||
|
||||
UpdateNodeRequest:
|
||||
type: object
|
||||
properties:
|
||||
label:
|
||||
type: string
|
||||
icon:
|
||||
type: string
|
||||
color:
|
||||
type: string
|
||||
bg_color:
|
||||
type: string
|
||||
|
||||
DisplayMode:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
sort_options:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/SortOption'
|
||||
filter_options:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/FilterOption'
|
||||
|
||||
SortOption:
|
||||
type: object
|
||||
properties:
|
||||
key:
|
||||
type: string
|
||||
label:
|
||||
type: string
|
||||
|
||||
FilterOption:
|
||||
type: object
|
||||
properties:
|
||||
key:
|
||||
type: string
|
||||
label:
|
||||
type: string
|
||||
|
||||
FileInfo:
|
||||
type: object
|
||||
properties:
|
||||
file_uuid:
|
||||
type: string
|
||||
original_name:
|
||||
type: string
|
||||
file_size:
|
||||
type: integer
|
||||
file_type:
|
||||
type: string
|
||||
registered_at:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
Reference in New Issue
Block a user