新增接口文档

2026-03-20 19:31:02 +08:00
parent 7efb86ed3a
commit d39d310544
7 changed files with 101 additions and 17 deletions
--- 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<ConvertRunVo> 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<ConvertHistoryVo> history() {
        ConvertHistoryVo vo = new ConvertHistoryVo();
        vo.setItems(convertRunService.listHistory());
@@ -66,14 +78,22 @@ public class ConvertRunController {

    @DeleteMapping("/history/{resultId}")
    @Operation(summary = "删除格式转换历史", description = "删除一条格式转换历史记录。")
-    public ApiResponse<Void> 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<Void> 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<Resource> 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<Resource> 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()
--- 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<List<ConvertTemplateVo>> 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<ConvertTemplateVo> importTemplate(@RequestBody ConvertTemplateImportRequest request) {
        return ApiResponse.success(convertTemplateService.importTemplate(request));
    }

    @PostMapping("/{templateCode}/default")
    @Operation(summary = "设为默认模板", description = "将指定模板设为默认模板。")
-    public ApiResponse<Void> 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<Void> setDefault(@Parameter(description = "模板编码", required = true) @PathVariable String templateCode) {
        convertTemplateService.setDefaultTemplate(templateCode);
        return ApiResponse.success(null);
    }

    @DeleteMapping("/{templateCode}")
    @Operation(summary = "删除模板", description = "删除指定模板。内置模板不允许删除。")
-    public ApiResponse<Void> 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<Void> delete(@Parameter(description = "模板编码", required = true) @PathVariable String templateCode) {
        convertTemplateService.deleteTemplate(templateCode);
        return ApiResponse.success(null);
    }