{"openapi":"3.1.0","info":{"title":"zeroweb-service-file","version":"v1"},"servers":[{"url":"http://localhost:10021","description":"Generated server url"}],"tags":[{"name":"fs-http-endpoint","description":"上传/下载附件到文件系统"},{"name":"attachment-http-endpoint","description":"附件管理"},{"name":"metadata-http-endpoint","description":"服务自省"}],"paths":{"/fs/{id}/upload":{"put":{"tags":["fs-http-endpoint"],"summary":"上传文件到服务器磁盘","description":"上传文件到服务器磁盘","operationId":"upload","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}}],"requestBody":{"description":"文件内容","content":{"application/json":{"schema":{"type":"string","format":"byte","minLength":1}}},"required":true},"responses":{"200":{"description":"OK"}}}},"/fs/{id}/upload/{partNumber}":{"put":{"tags":["fs-http-endpoint"],"summary":"上传文件分段到服务器磁盘","description":"上传文件分段到服务器磁盘","operationId":"upload_1","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}},{"name":"partNumber","in":"path","description":"分段序号","required":true,"schema":{"type":"integer","format":"int32","exclusiveMinimum":0,"maximum":10000}}],"requestBody":{"description":"文件内容","content":{"application/json":{"schema":{"type":"string","format":"byte","minLength":1}}},"required":true},"responses":{"200":{"description":"OK"}}}},"/attachment/{id}/status/done":{"put":{"tags":["attachment-http-endpoint"],"summary":"文件上传完成后，将其状态变更为已完成","description":"文件上传完成后，将其状态变更为已完成","operationId":"finishUpload","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK"}}}},"/attachment":{"post":{"tags":["attachment-http-endpoint"],"summary":"新增附件","description":"新增附件","operationId":"addAttachment","parameters":[{"name":"crc","in":"query","description":"文件的 CRC 值。虽然只有 S3 服务需要，但是建议调用接口时必传。","required":false,"schema":{"type":"string"}}],"requestBody":{"description":"文件信息","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAttachmentReq"}}},"required":true},"responses":{"200":{"description":"文件上传元数据","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UploadInfo"}}}}}}},"/metadata/menu.json":{"get":{"tags":["metadata-http-endpoint"],"summary":"获取当前服务提供的所有菜单或资源信息。","description":"获取当前服务提供的所有菜单或资源信息。","operationId":"loadResourceInfo","responses":{"200":{"description":"包含所有 [MenuInfo] 对象的列表，聚合了所有 [IMenuService] 的结果。","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MenuInfo"}}}}}}}},"/metadata/info.json":{"get":{"tags":["metadata-http-endpoint"],"summary":"获取当前服务的自省信息。","description":"获取当前服务的自省信息。","operationId":"loadServiceInfo","responses":{"200":{"description":"包含服务名称、版本、类型等信息的 [ServiceInfo] 对象。","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ServiceInfo"}}}}}}},"/fs/{id}/download":{"get":{"tags":["fs-http-endpoint"],"summary":"下载文件","description":"下载文件","operationId":"download","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"文件内容","content":{"*/*":{"schema":{"type":"string","format":"byte"}}}}}}},"/attachment/{id}":{"get":{"tags":["attachment-http-endpoint"],"summary":"查询指定附件","description":"查询指定附件","operationId":"queryById","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"附件信息","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Attachment"}}}}}},"delete":{"tags":["attachment-http-endpoint"],"summary":"删除附件","description":"删除附件","operationId":"deleteAttachment","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK"}}}},"/attachment/{id}/resume":{"get":{"tags":["attachment-http-endpoint"],"summary":"获取附件上传元信息","description":"获取附件上传元信息","operationId":"getUploadInfo","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}},{"name":"checksum","in":"query","description":"附件的内容摘要。与 `fileSize` 联合校验续传内容与之前的内容一致。","required":true,"schema":{"type":"string","minLength":1}},{"name":"fileSize","in":"query","description":"附件的大小。","required":true,"schema":{"type":"integer","format":"int64","exclusiveMinimum":0}},{"name":"crc","in":"query","description":"文件的 CRC 值。虽然只有 S3 服务需要，但是建议调用接口时必传。","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"上传元信息","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UploadInfo"}}}}}}},"/attachment/{id}/endpoint/upload":{"get":{"tags":["attachment-http-endpoint"],"summary":"获取附件上传地址","description":"获取附件上传地址","operationId":"getUploadEndpoint","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}},{"name":"partNumber","in":"query","description":"分段序号","required":false,"schema":{"type":"integer","format":"int32","default":0,"maximum":10000,"minimum":0}},{"name":"crc","in":"query","description":"文件的 CRC 值。虽然只有 S3 服务需要，但是建议调用接口时必传。","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"附件上传地址","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UploadEndpoint"}}}}}}},"/attachment/{id}/endpoint/download":{"get":{"tags":["attachment-http-endpoint"],"summary":"获取附件下载地址","description":"获取附件下载地址","operationId":"getDownloadEndpoint","parameters":[{"name":"id","in":"path","description":"附件ID","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"附件下载地址","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DownloadEndpoint"}}}}}}},"/attachment/page":{"get":{"tags":["attachment-http-endpoint"],"summary":"分页查询附件列表","description":"分页查询附件列表","operationId":"queryPage","parameters":[{"name":"odata","in":"query","description":"查询参数","required":true,"schema":{"$ref":"#/components/schemas/ODataRequestParam"}}],"responses":{"200":{"description":"附件列表","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PagedModelAttachment"}}}}}}},"/attachment/list":{"get":{"tags":["attachment-http-endpoint"],"summary":"查询表单关联的附件","description":"查询表单关联的附件","operationId":"queryByBiz","parameters":[{"name":"bizType","in":"query","description":"业务类型","required":true,"schema":{"type":"string","minLength":1}},{"name":"bizId","in":"query","description":"业务ID","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"附件信息集合（不包含下载地址）","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}}}}}}},"components":{"schemas":{"AddAttachmentReq":{"type":"object","description":"新增附件请求体","properties":{"name":{"type":"string","description":"文件名","maxLength":255,"minLength":0},"checksum":{"type":"string","description":"文件摘要","maxLength":128,"minLength":0},"size":{"type":"integer","format":"int64","description":"文件大小。单位：字节。"},"type":{"type":"string","description":"MIME 类型","maxLength":255,"minLength":0},"bizType":{"type":"string","description":"业务类型","maxLength":255,"minLength":0},"bizId":{"type":"string","description":"业务 ID"}},"required":["bizType","checksum","name","size","type"]},"UploadInfo":{"type":"object","description":"文件上传信息","properties":{"id":{"type":"string","description":"附件ID"},"provider":{"type":"string","description":"存储提供商","enum":["FS","S3"]},"partCount":{"type":"integer","format":"int32","description":"分片数量"},"partSize":{"type":"integer","format":"int64","description":"分片大小。单位 Byte。"}}},"MenuInfo":{"type":"object","description":"菜单或资源的信息封装类。\n用于描述前端菜单、外部链接、嵌入页面以及后端接口权限和资源权限等。","properties":{"type":{"type":"string","description":"菜单或资源的具体类型，例如路由、外部链接、接口权限等。","enum":["ROUTE","EXTERNAL_LINK","EMBEDDED","PERMISSION","GROUP_PERMISSION"]},"path":{"type":"string","description":"菜单或资源的路径。\n不同类型的资源有不同的路径格式，详见 [MenuType]。"},"permissions":{"type":"array","description":"访问此菜单或资源所需要的权限集合。\n取并集，即访问者必须满足列表中所有权限才能访问。","items":{"type":"string"}}}},"ServiceInfo":{"type":"object","description":"服务元数据信息封装类。\n包含服务的名称、版本、类型以及是否隐藏等信息，用于服务自省。","properties":{"name":{"type":"string","description":"服务的名称，例如 \"user-service\" 或 \"product-service\"。"},"version":{"type":"string","description":"服务的版本，例如 \"1.0.0\"。"},"type":{"type":"string","description":"服务的类型，例如 [ServiceType#CLIENT] (前端) 或 [ServiceType#SERVER] (后端)。\n默认为 [ServiceType#SERVER]。","enum":["CLIENT","SERVER"]},"hidden":{"type":"boolean","description":"指示服务是否应该在站内链接中隐藏。\n如果为 `true`，则通常不应在公共菜单或服务列表中显示。\n默认为 `true`。"}}},"Attachment":{"type":"object","description":"附件实体类，表示系统中存储的文件附件。","properties":{"id":{"type":"string","description":"附件的唯一标识符。"},"name":{"type":"string","description":"原始文件名，包含扩展名。"},"checksum":{"type":"string","description":"文件的内容摘要，用于验证文件完整性和唯一性。\n 通常是文件的哈希值。"},"size":{"type":"integer","format":"int64","description":"文件的大小。\n单位：`字节`。"},"type":{"type":"string","description":"文件的 MIME 类型，例如 `image/jpeg`、`application/pdf`。"},"bizType":{"type":"string","description":"附件所属的业务类型。"},"bizId":{"type":"string","description":"附件所属业务实体的ID。\n与 [#bizType] 结合使用以关联附件。"},"provider":{"type":"string","description":"文件存储的后端提供者。","enum":["FS","S3"]},"status":{"type":"string","description":"附件的当前状态。","enum":["UPLOADING","DONE"]},"ownerId":{"type":"string","description":"上传此附件的用户ID。"},"createTime":{"type":"string","format":"date-time","description":"附件的上传时间。\n使用 [Instant] 存储，并由 [CreatedDate] 自动设置。"}}},"UploadEndpoint":{"type":"object","description":"附件上传地址","properties":{"partNumber":{"type":"integer","format":"int32","description":"分段序号"},"endpoint":{"type":"string","description":"上传地址"}}},"DownloadEndpoint":{"type":"object","description":"附件下载地址","properties":{"endpoint":{"type":"string","description":"下载地址"},"filename":{"type":"string","description":"文件名"}}},"ODataRequestParam":{"type":"object","description":"OData 请求参数","properties":{"top":{"type":"integer","format":"int32","description":"最大返回条数"},"skip":{"type":"integer","format":"int32","description":"偏移量"}}},"PageMetadata":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"number":{"type":"integer","format":"int64"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int64"}}},"PagedModelAttachment":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}}}}}