# Copyright 2019 A2OS SafeU Dev Team # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. openapi: 3.0.0 info: title: A2OS SafeU description: | A2OS SafeU 项目 API 文档。 contact: email: a2os-general@googlegroups.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: "1.0.0-beta" externalDocs: description: Find out more about A2OS SafeU backend url: https://api.safeu.a2os.club tags: - name: upload description: Upload item(s) operations - name: update description: Update item(s) operations - name: delete description: delete item(s) operations - name: download description: Download item(s) operations - name: validation description: Validation operations - name: miscellaneous description: Miscellaneous operations paths: /ping: get: tags: - miscellaneous summary: PING-PONG operationId: ping responses: "200": description: 节点正常 content: "application/json": schema: type: object properties: message: type: string description: 返回信息 example: pong /csrf: get: tags: - miscellaneous summary: CSRF 口令获得接口 operationId: getCSRFToken responses: "200": description: 获得 CSRF 口令 headers: X-CSRF-TOKEN: description: CSRF 口令 schema: type: string content: "text/plain": schema: type: string description: 返回信息 example: IN HEADER /v1/info/{retrieveCode}: post: tags: - miscellaneous summary: 文件(组)信息获取接口 operationId: getFileInfo parameters: - name: retrieveCode in: path description: 提取码 required: true schema: type: string - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 responses: "200": description: 获得文件信息 content: "application/json": schema: type: object properties: down_count: type: integer format: int64 description: 可下载次数 expired_at: type: string format: date-time description: 文件到期时间 is_public: type: boolean description: 文件是否加密 "400": description: 无法获得请求参数 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "401": description: 认证失败 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/upload/policy: get: tags: - upload summary: 上传策略请求 responses: "200": description: 成功获得上传策略 content: "application/json": schema: type: object properties: accessid: type: string description: 用户请求的accessid host: type: string description: 用户要往哪个域名发送上传请求 expire: type: string description: 上传策略Policy失效时间,在服务端指定。失效时间之前都可以利用此Policy上传文件,无需每次上传都去服务端获取签名 signature: type: string description: 对变量policy签名后的字符串 policy: type: string description: 用户表单上传的策略(Policy),是经过base64编码过的字符串 dir: type: string description: 上传路径 callback: type: string description: 回调设置代码,采用base64编码 /v1/upload/callback: post: tags: - upload summary: 阿里云OSS回调用户文件信息,鉴权后返回结果由OSS转发给用户 responses: "200": description: authorization验证通过 content: "application/json": schema: type: object properties: uuid: type: string description: 文件uuid /v1/upload/finish: post: tags: - upload summary: 结束所有上传文件的上传操作 parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: files: type: array items: type: string example: fe5305b4-e0c8-490b-b3dc-eb523e699a07 description: 文件列表 responses: "200": description: 结束文件上传成功 content: "application/json": schema: type: object properties: owner: type: string description: 文件所有者信息 recode: type: string description: 文件提取码 /v1/password/{retrieveCode}: post: tags: - update summary: 修改文件密码 operationId: changeFilePassword parameters: - name: retrieveCode in: path description: 提取码 required: true schema: type: string - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 auth: type: string description: 哈希后的密码 如果为空 则取消设置密码 responses: "200": description: 成功修改文件密码 content: "application/json": schema: type: object properties: message: type: "string" example: ok description: 修改成功 "401": description: 文件所有者信息不存在 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/recode/{retrieveCode}: post: tags: - update summary: 修改文件提取码 operationId: changeFileRetrieveCode parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 new_re_code: type: string description: 新的提取码 auth: type: string description: 新的哈希过的密码 如果修改的文件此前有密码需要提供此字段 responses: "200": description: 成功修改文件提取码 content: "application/json": schema: type: object properties: message: type: "string" example: ok description: 修改成功 "400": description: 提供字段不正确 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "401": description: 文件所有者信息不存在 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/expireTime/{retrieveCode}: post: tags: - update summary: 修改文件过期时间 operationId: changeFileExpireTime parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 new_expire_time: type: number example: 1-24 description: 文件新过期时间 responses: "200": description: 成功修改文件过期时间 content: "application/json": schema: type: object properties: message: type: "string" example: 2019-02-19T19:28:32+08:00 description: 修改成功返回新的过期时间 "400": description: 新的文件过期时间不正确 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "401": description: 文件所有者信息不存在 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/delete/{retrieveCode}: post: tags: - delete summary: 手动删除文件接口 operationId: deleteFileManual parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 responses: "200": description: 成功修改删除文件 content: "application/json": schema: type: object properties: message: type: "string" example: ok description: 删除成功 "401": description: 文件所有者信息不存在 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/downCount/{retrieveCode}: post: tags: - update summary: 修改文件下载次数 operationId: changeFileDownCount parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: user_token: type: string description: 文件所有者信息 new_down_count: type: string description: 新的下载次数 responses: "200": description: 成功修改文件下载次数 content: "application/json": schema: type: object properties: message: type: "string" example: ok description: 修改成功 "401": description: 文件所有者信息不存在 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/minusDownCount/{retrieveCode}: post: tags: - download summary: 下载感知接口 operationId: downloadAwareness parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: bucket: description: 文件所在 OSS 桶名 type: string path: description: 文件所在 OSS 桶中的绝对路径 type: string responses: "200": description: 成功接收下载信息 content: "text/plain": schema: type: string description: 数据操作(OK,MINUS,DELETED) "404": description: 无法找到资源 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 服务器错误 content: "text/plain": schema: type: string description: 未知错误 /v1/item/{retrieveCode}: post: tags: - download summary: 获取下载/打包文件连接 operationId: downloadItem parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: Token in: header description: 临时认证口令 style: simple required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: $ref: "#/components/schemas/PackRequest" responses: "200": description: 成功获取文件(组)下载链接 content: "application/json": schema: type: object properties: url: type: string description: 文件(组)下载链接 "400": description: 无法获得文件列表 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "401": description: 认证失败 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "404": description: 无法找到资源/认证口令 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "410": description: 下载次数耗尽 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 无法获取签名下载链接 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "503": description: 无法提供服务 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 /v1/validation/{retrieveCode}: post: tags: - validation summary: 提取码认证接口 operationId: validateRC parameters: - name: X-CSRF-TOKEN in: header description: CSRF 口令 required: true schema: type: string - name: retrieveCode in: path description: 提取码 required: true schema: type: string requestBody: content: "application/json": schema: type: object properties: password: type: string description: 文件提取密码 responses: "200": description: 认证成功 content: "application/json": schema: type: object properties: token: type: string description: 临时认证口令 items: $ref: "#/components/schemas/ResponseItemGroup" "401": description: 需要密码 / 密码认证失败 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "404": description: 无法通过该提取码找到文件 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 "500": description: 资源不可用 content: "application/json": schema: type: object properties: err_code: type: integer format: int64 description: 错误码 message: type: string description: 错误原因 components: schemas: ResponseItem: type: object description: 文件 properties: name: type: string description: 存储单位 UUID 值 original_name: type: string description: 文件原名 down_count: type: integer format: int32 description: 可下载次数 type: type: string description: 文件类型 protocol: type: string description: OSS 下载协议 bucket: type: string description: 文件所在 OSS 桶名 endpoint: type: string description: OSS 地域路径 path: type: string description: 文件所在 OSS 桶中的绝对路径 expired_at: type: string format: date-time description: 文件到期时间 ResponseItemGroup: type: array items: $ref: "#/components/schemas/ResponseItem" description: 文件组 ZipItem: type: object description: 待下载文件 properties: protocol: type: string description: OSS 下载协议 bucket: type: string description: 文件所在 OSS 桶名 endpoint: type: string description: OSS 地域路径 path: type: string description: 文件所在 OSS 桶中的绝对路径 original_name: type: string description: 文件原名 PackRequest: type: object description: 打包/下载链接请求 properties: full: type: boolean description: 是否为该提取码下的全部文件 items: type: array description: 待打包/下载文件 items: $ref: "#/components/schemas/ZipItem"