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