{ "components": { "responses": { "Error": { "content": { "application/json": { "example": { "error": "请求失败", "error_code": "EXAMPLE_ERROR", "message": "请求失败", "ok": false }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "请求失败" } }, "schemas": { "CreateTokenRequest": { "additionalProperties": false, "properties": { "background_color": { "description": "预览工作区背景色", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, "copyable": { "default": true, "description": "是否允许复制", "type": "boolean" }, "expire": { "description": "Token 有效分钟数", "minimum": 0, "type": "integer" }, "idempotency_key": { "description": "业务唯一幂等键；重复请求不重复计费", "maxLength": 255, "minLength": 1, "type": "string" }, "ip": { "type": "string" }, "limit": { "description": "最多展示页数", "minimum": 0, "type": "integer" }, "max_views": { "description": "最大访问次数", "minimum": 0, "type": "integer" }, "password": { "type": "string", "writeOnly": true }, "printable": { "default": true, "description": "是否允许打印", "type": "boolean" }, "saveable": { "default": true, "description": "是否允许下载", "type": "boolean" }, "src": { "description": "服务端可访问的公网文件 URL", "format": "uri", "type": "string" }, "title": { "maxLength": 255, "type": "string" }, "toolbar": { "default": true, "description": "是否显示工具栏", "type": "boolean" }, "toolbar_color": { "description": "工具栏颜色", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, "watermark": { "type": "string" }, "watermark_image": { "type": "string" } }, "required": [ "src", "idempotency_key" ], "type": "object" }, "ErrorResponse": { "properties": { "error": { "type": "string" }, "error_code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" }, "ok": { "const": false, "type": "boolean" }, "request_id": { "type": "string" }, "retry_after_seconds": { "type": "integer" } }, "required": [ "ok", "error", "error_code", "message" ], "type": "object" }, "KeyInfoResponse": { "properties": { "created_at": { "type": [ "string", "null" ] }, "expire_at": { "type": [ "string", "null" ] }, "file_ttl": { "type": "integer" }, "is_expired": { "type": "boolean" }, "name": { "type": "string" }, "quota_pct": { "type": "number" }, "quota_total": { "type": "integer" }, "quota_used": { "type": "integer" }, "rate_limit": { "type": "integer" }, "remark": { "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "type": "object" }, "TokenResponse": { "properties": { "idempotent": { "type": "boolean" }, "token": { "type": "string" }, "view_url": { "format": "uri", "type": "string" } }, "required": [ "token", "view_url" ], "type": "object" }, "UploadRequest": { "additionalProperties": false, "properties": { "background_color": { "description": "预览工作区背景色", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, "copyable": { "default": true, "description": "是否允许复制", "type": "boolean" }, "expire": { "description": "Token 有效分钟数", "minimum": 0, "type": "integer" }, "file": { "description": "待预览文件，默认最大 100MB", "format": "binary", "type": "string" }, "ip": { "type": "string" }, "max_views": { "description": "最大访问次数", "minimum": 0, "type": "integer" }, "password": { "type": "string", "writeOnly": true }, "printable": { "default": true, "description": "是否允许打印", "type": "boolean" }, "saveable": { "default": true, "description": "是否允许下载", "type": "boolean" }, "title": { "maxLength": 255, "type": "string" }, "toolbar": { "default": true, "description": "是否显示工具栏", "type": "boolean" }, "toolbar_color": { "description": "工具栏颜色", "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, "watermark": { "type": "string" }, "watermark_image": { "type": "string" } }, "required": [ "file" ], "type": "object" }, "UploadResponse": { "properties": { "file_expire_at": { "type": "string" }, "oss_warning": { "type": "string" }, "src": { "type": "string" }, "token": { "type": "string" }, "view_url": { "format": "uri", "type": "string" } }, "required": [ "token", "view_url", "src" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "推荐方式：通过请求头传递客户 API Key。可选 HMAC 请求同时携带 X-Api-Timestamp 与 X-Api-Signature。", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "ApiKeyQuery": { "description": "兼容方式：通过查询参数传递 API Key。", "in": "query", "name": "api_key", "type": "apiKey" } } }, "info": { "contact": { "name": "上海多聚米科技有限公司" }, "description": "企业文件在线预览服务公开接入合同。HTML 预览地址由 view_url 返回。", "title": "DJM Preview 公开接入 API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/key-info": { "get": { "operationId": "getKeyInfo", "parameters": [ { "description": "启用 HMAC 时必填的 Unix 秒级时间戳。", "in": "header", "name": "X-Api-Timestamp", "required": false, "schema": { "type": "string" } }, { "description": "可选 HMAC-SHA256 十六进制签名。", "in": "header", "name": "X-Api-Signature", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-02 10:00:00", "expire_at": null, "file_ttl": 86400, "is_expired": false, "name": "示例客户", "quota_pct": 16.7, "quota_total": 30, "quota_used": 5, "rate_limit": 60, "status": "active" }, "schema": { "$ref": "#/components/schemas/KeyInfoResponse" } } }, "description": "API Key 信息" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ], "summary": "查询 API Key 状态与额度", "tags": [ "公开接入" ] } }, "/api/token": { "post": { "operationId": "createPreviewToken", "parameters": [ { "description": "启用 HMAC 时必填的 Unix 秒级时间戳。", "in": "header", "name": "X-Api-Timestamp", "required": false, "schema": { "type": "string" } }, { "description": "可选 HMAC-SHA256 十六进制签名。", "in": "header", "name": "X-Api-Signature", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "idempotency_key": "contract-2026-0001", "saveable": false, "src": "https://files.example.com/contracts/sample.docx", "title": "合同预览", "watermark": "内部资料" }, "schema": { "$ref": "#/components/schemas/CreateTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "token": "token_example_placeholder", "view_url": "https://preview.example.com/view?token=token_example_placeholder" }, "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Token 创建或幂等复用成功" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ], "summary": "创建预览 Token", "tags": [ "公开接入" ] } }, "/api/upload": { "post": { "operationId": "uploadPreviewFile", "parameters": [ { "description": "启用 HMAC 时必填的 Unix 秒级时间戳。", "in": "header", "name": "X-Api-Timestamp", "required": false, "schema": { "type": "string" } }, { "description": "可选 HMAC-SHA256 十六进制签名。", "in": "header", "name": "X-Api-Signature", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "src": "受保护的服务端文件标识", "token": "token_example_placeholder", "view_url": "https://preview.example.com/view?token=token_example_placeholder" }, "schema": { "$ref": "#/components/schemas/UploadResponse" } } }, "description": "上传和 Token 创建成功" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ], "summary": "上传文件并创建预览", "tags": [ "公开接入" ] } } } }