e3d6b60825
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%
753 lines
17 KiB
YAML
753 lines
17 KiB
YAML
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 |