From fb32f7bd355fe581ede8a957e0773fc579e31646 Mon Sep 17 00:00:00 2001 From: super <2903208875@qq.com> Date: Fri, 20 Mar 2026 19:31:02 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=8E=A5=E5=8F=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend-java/pom.xml | 6 ----- .../controller/ConvertRunController.java | 24 +++++++++++++++++-- .../controller/ConvertTemplateController.java | 24 +++++++++++++++++-- .../controller/DedupeRunController.java | 24 +++++++++++++++++-- .../file/controller/FileUploadController.java | 14 ++++++++++- .../split/controller/SplitRunController.java | 24 +++++++++++++++++-- .../src/main/resources/application.yml | 2 -- 7 files changed, 101 insertions(+), 17 deletions(-) diff --git a/backend-java/pom.xml b/backend-java/pom.xml index 7f2ff65..bf45bcb 100644 --- a/backend-java/pom.xml +++ b/backend-java/pom.xml @@ -17,7 +17,6 @@ 21 - 2.6.0 4.5.0 3.5.7 1.5.5.Final @@ -63,11 +62,6 @@ aliyun-sdk-oss ${aliyun.oss.version} - - org.springdoc - springdoc-openapi-starter-webmvc-ui - ${springdoc.version} - com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertRunController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertRunController.java index 49ed3c7..babd8f6 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertRunController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertRunController.java @@ -6,6 +6,10 @@ import com.nanri.aiimage.modules.convert.model.vo.ConvertHistoryVo; import com.nanri.aiimage.modules.convert.model.vo.ConvertRunVo; import com.nanri.aiimage.modules.convert.service.ConvertRunService; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +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 jakarta.validation.Valid; import lombok.RequiredArgsConstructor; @@ -52,12 +56,20 @@ public class ConvertRunController { 输出文件名遵循模板配置的 outputFilename，若临时目录中重名则自动追加序号。 """) + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "执行成功，返回转换结果统计", content = @Content(schema = @Schema(implementation = ConvertRunVo.class))), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "请求参数不合法或模板不存在"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "执行格式转换失败") + }) public ApiResponse run(@Valid @RequestBody ConvertRunRequest request) { return ApiResponse.success(convertRunService.run(request)); } @GetMapping("/history") @Operation(summary = "查询格式转换历史", description = "查询最近的格式转换成功记录，用于页面右侧历史下载列表展示。") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = ConvertHistoryVo.class))) + }) public ApiResponse history() { ConvertHistoryVo vo = new ConvertHistoryVo(); vo.setItems(convertRunService.listHistory()); @@ -66,14 +78,22 @@ public class ConvertRunController { @DeleteMapping("/history/{resultId}") @Operation(summary = "删除格式转换历史", description = "删除一条格式转换历史记录。") - public ApiResponse deleteHistory(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "删除成功"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果记录不存在") + }) + public ApiResponse deleteHistory(@Parameter(description = "格式转换结果记录 ID", required = true) @PathVariable Long resultId) { convertRunService.deleteHistory(resultId); return ApiResponse.success(null); } @GetMapping("/results/{resultId}/download") @Operation(summary = "下载格式转换结果", description = "根据结果记录 ID 下载已生成的转换结果文件。桌面端前端可继续通过 save_file_from_url 选择保存位置。") - public ResponseEntity download(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "返回结果文件流"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果文件不存在") + }) + public ResponseEntity download(@Parameter(description = "格式转换结果记录 ID", required = true) @PathVariable Long resultId) { File resultFile = convertRunService.getResultFile(resultId); String encodedFilename = URLEncoder.encode(resultFile.getName(), StandardCharsets.UTF_8).replaceAll("\\+", "%20"); return ResponseEntity.ok() diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertTemplateController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertTemplateController.java index 370dc97..5132dae 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertTemplateController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/convert/controller/ConvertTemplateController.java @@ -5,6 +5,10 @@ import com.nanri.aiimage.modules.convert.model.dto.ConvertTemplateImportRequest; import com.nanri.aiimage.modules.convert.model.vo.ConvertTemplateVo; import com.nanri.aiimage.modules.convert.service.ConvertTemplateService; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +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.DeleteMapping; @@ -27,26 +31,42 @@ public class ConvertTemplateController { @GetMapping @Operation(summary = "查询启用模板", description = "返回当前启用的格式转换模板列表，供前端‘格式转换’模块展示。") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功，返回模板列表") + }) public ApiResponse> listTemplates() { return ApiResponse.success(convertTemplateService.listEnabledTemplates()); } @PostMapping("/import") @Operation(summary = "导入模板", description = "导入自定义 txt 模板，成功后返回新模板并可立即刷新模板列表。") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "导入成功，返回新模板信息", content = @Content(schema = @Schema(implementation = ConvertTemplateVo.class))), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "模板内容不合法或必填字段缺失") + }) public ApiResponse importTemplate(@RequestBody ConvertTemplateImportRequest request) { return ApiResponse.success(convertTemplateService.importTemplate(request)); } @PostMapping("/{templateCode}/default") @Operation(summary = "设为默认模板", description = "将指定模板设为默认模板。") - public ApiResponse setDefault(@PathVariable String templateCode) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "设置成功"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "模板不存在") + }) + public ApiResponse setDefault(@Parameter(description = "模板编码", required = true) @PathVariable String templateCode) { convertTemplateService.setDefaultTemplate(templateCode); return ApiResponse.success(null); } @DeleteMapping("/{templateCode}") @Operation(summary = "删除模板", description = "删除指定模板。内置模板不允许删除。") - public ApiResponse delete(@PathVariable String templateCode) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "删除成功"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "内置模板不允许删除"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "模板不存在") + }) + public ApiResponse delete(@Parameter(description = "模板编码", required = true) @PathVariable String templateCode) { convertTemplateService.deleteTemplate(templateCode); return ApiResponse.success(null); } diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeRunController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeRunController.java index 6cf2987..4e9c247 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeRunController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeRunController.java @@ -6,6 +6,10 @@ import com.nanri.aiimage.modules.dedupe.model.vo.DedupeHistoryVo; import com.nanri.aiimage.modules.dedupe.model.vo.DedupeRunVo; import com.nanri.aiimage.modules.dedupe.service.DedupeRunService; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +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 jakarta.validation.Valid; import lombok.RequiredArgsConstructor; @@ -43,12 +47,20 @@ public class DedupeRunController { - keepUnderscoreIds=true 时保留类似 1_1 的 ID； - 输出文件命名遵循 原文件名_cleaned.xlsx，若重名自动追加序号。 """) + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "执行成功，返回处理统计与结果列表", content = @Content(schema = @Schema(implementation = DedupeRunVo.class))), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "请求参数不合法或缺少必要字段"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "执行数据去重失败") + }) public ApiResponse run(@Valid @RequestBody DedupeRunRequest request) { return ApiResponse.success(dedupeRunService.run(request)); } @GetMapping("/history") @Operation(summary = "查询去重历史", description = "查询最近的去重成功记录，用于页面右侧历史下载列表展示。") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = DedupeHistoryVo.class))) + }) public ApiResponse history() { DedupeHistoryVo vo = new DedupeHistoryVo(); vo.setItems(dedupeRunService.listHistory()); @@ -57,14 +69,22 @@ public class DedupeRunController { @DeleteMapping("/history/{resultId}") @Operation(summary = "删除去重历史", description = "删除一条去重历史记录。") - public ApiResponse deleteHistory(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "删除成功"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果记录不存在") + }) + public ApiResponse deleteHistory(@Parameter(description = "去重结果记录 ID", required = true) @PathVariable Long resultId) { dedupeRunService.deleteHistory(resultId); return ApiResponse.success(null); } @GetMapping("/results/{resultId}/download") @Operation(summary = "下载数据去重结果", description = "根据结果记录 ID 下载清洗后的 Excel 文件。") - public ResponseEntity download(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "返回结果文件流"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果文件不存在") + }) + public ResponseEntity download(@Parameter(description = "去重结果记录 ID", required = true) @PathVariable Long resultId) { Resource resource = dedupeRunService.getResultFile(resultId); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/file/controller/FileUploadController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/file/controller/FileUploadController.java index 19d14a0..0f61e6c 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/file/controller/FileUploadController.java +++ b/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 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 upload( + @Parameter(name = "file", description = "待上传的 Excel 或业务源文件", required = true, in = ParameterIn.QUERY) + MultipartFile file) throws Exception { return ApiResponse.success(localFileStorageService.saveTempFile(file)); } } diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/split/controller/SplitRunController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/split/controller/SplitRunController.java index 2057e1a..d46a0c2 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/split/controller/SplitRunController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/split/controller/SplitRunController.java @@ -6,6 +6,10 @@ import com.nanri.aiimage.modules.split.model.vo.SplitHistoryVo; import com.nanri.aiimage.modules.split.model.vo.SplitRunVo; import com.nanri.aiimage.modules.split.service.SplitRunService; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +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 jakarta.validation.Valid; import lombok.RequiredArgsConstructor; @@ -44,12 +48,20 @@ public class SplitRunController { - 输出文件命名遵循 原文件名_split_序号.xlsx； - 返回结果中 rowCount 表示该结果文件包含的数据行数。 """) + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "执行成功，返回拆分结果统计", content = @Content(schema = @Schema(implementation = SplitRunVo.class))), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "请求参数不合法或拆分模式错误"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "500", description = "执行数据拆分失败") + }) public ApiResponse run(@Valid @RequestBody SplitRunRequest request) { return ApiResponse.success(splitRunService.run(request)); } @GetMapping("/history") @Operation(summary = "查询数据拆分历史", description = "查询最近的数据拆分成功记录，用于页面右侧历史下载列表展示。") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = SplitHistoryVo.class))) + }) public ApiResponse history() { SplitHistoryVo vo = new SplitHistoryVo(); vo.setItems(splitRunService.listHistory()); @@ -58,14 +70,22 @@ public class SplitRunController { @DeleteMapping("/history/{resultId}") @Operation(summary = "删除数据拆分历史", description = "删除一条数据拆分历史记录。") - public ApiResponse deleteHistory(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "删除成功"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果记录不存在") + }) + public ApiResponse deleteHistory(@Parameter(description = "数据拆分结果记录 ID", required = true) @PathVariable Long resultId) { splitRunService.deleteHistory(resultId); return ApiResponse.success(null); } @GetMapping("/results/{resultId}/download") @Operation(summary = "下载数据拆分结果", description = "根据结果记录 ID 下载拆分后的 Excel 文件。") - public ResponseEntity download(@PathVariable Long resultId) { + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "返回结果文件流"), + @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "结果文件不存在") + }) + public ResponseEntity download(@Parameter(description = "数据拆分结果记录 ID", required = true) @PathVariable Long resultId) { Resource resource = splitRunService.getResultFile(resultId); return ResponseEntity.ok() .contentType(MediaType.APPLICATION_OCTET_STREAM) diff --git a/backend-java/src/main/resources/application.yml b/backend-java/src/main/resources/application.yml index 362a417..2c6a7d3 100644 --- a/backend-java/src/main/resources/application.yml +++ b/backend-java/src/main/resources/application.yml @@ -30,8 +30,6 @@ mybatis-plus: springdoc: api-docs: enabled: true - swagger-ui: - path: /swagger-ui.html knife4j: enable: true