新增接口文档

backend-java/src/main/java/com/nanri/aiimage/modules/file/controller/FileUploadController.java

@@ -4,6 +4,11 @@ import com.nanri.aiimage.common.api.ApiResponse;
 import com.nanri.aiimage.modules.file.model.vo.UploadFileVo;
 import com.nanri.aiimage.modules.file.service.LocalFileStorageService;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -31,7 +36,14 @@ public class FileUploadController {
                     - 然后把 fileKey 传给 dedupe/convert/split 执行接口；
                     - 处理完成后，桌面端再调用下载接口把结果文件保存回用户本地目录。
                     """)
-    public ApiResponse<UploadFileVo> upload(MultipartFile file) throws Exception {
+    @ApiResponses({
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "上传成功，返回临时文件信息", content = @Content(schema = @Schema(implementation = UploadFileVo.class))),
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "未传文件或文件不合法"),
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "服务器保存临时文件失败")
+    })
+    public ApiResponse<UploadFileVo> upload(
+            @Parameter(name = "file", description = "待上传的 Excel 或业务源文件", required = true, in = ParameterIn.QUERY)
+            MultipartFile file) throws Exception {
         return ApiResponse.success(localFileStorageService.saveTempFile(file));
     }
 }