1. 添加策略模板API文档

2024-01-12 19:24:19 +08:00
parent c1a5d2462f
commit 8a719709a3
33 changed files with 450 additions and 222 deletions
--- a/src/main/java/com/realtime/protection/server/defense/object/ProtectObjectControllerApi.java
+++ b/src/main/java/com/realtime/protection/server/defense/object/ProtectObjectControllerApi.java
@@ -12,7 +12,6 @@ import jakarta.servlet.http.HttpServletResponse;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotNull;
-import org.apache.coyote.Response;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;

@@ -86,7 +85,10 @@ public interface ProtectObjectControllerApi {
                    )
            },
            parameters = {
-                    @Parameter()
+                    @Parameter(name = "proobj_name", description = "防护对象名称"),
+                    @Parameter(name = "proobj_id", description = "防护对象ID"),
+                    @Parameter(name = "page", description = "页码", example = "1"),
+                    @Parameter(name = "page_size", description = "每页的对象个数", example = "5")
            }
    )
    ResponseResult queryProtectObjects(@RequestParam(value = "proobj_name", required = false)
@@ -97,19 +99,102 @@ public interface ProtectObjectControllerApi {
                                       @RequestParam("page_size") @Min(1) Integer pageSize);

    @GetMapping("/{protectObjectId}/query")
+    @Operation(
+            summary = "查询单个防护对象",
+            description = "根据ID查询单个防护对象的信息",
+            responses = {
+                    @ApiResponse(
+                            description = "返回单个防护对象信息",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "protectObjectId", description = "防护对象ID", example = "2")
+            }
+    )
    ResponseResult queryProtectObject(@PathVariable Integer protectObjectId) throws IllegalAccessException;

    @PostMapping("/{protectObjectId}/update")
+    @Operation(
+            summary = "更新防护对象",
+            description = "根据防护对象ID和信息更新防护对象",
+            responses = {
+                    @ApiResponse(
+                            description = "防护对象更新情况",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "protectObjectId", description = "防护对象ID", example = "2")
+            },
+            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "防护对象更新信息")
+    )
    ResponseResult updateProtectObject(@PathVariable Integer protectObjectId,
                                       @RequestBody @Valid ProtectObject protectObject);

+
    @DeleteMapping("/{protectObjectId}/delete")
+    @Operation(
+            summary = "删除防护对象",
+            description = "根据防护对象ID删除对应防护对象",
+            responses = {
+                    @ApiResponse(
+                            description = "防护对象删除情况",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "protectObjectId", description = "欲删除的防护对象ID", example = "2")
+            }
+    )
    ResponseResult deleteProtectObject(@PathVariable Integer protectObjectId);

    @DeleteMapping("/delete/{protectObjectIds}")
+    @Operation(
+            summary = "批量删除防护对象",
+            description = "根据多个对象ID删除多个防护对象",
+            responses = {
+                    @ApiResponse(
+                            description = "防护对象删除情况",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "protectObjectIds", description = "欲删除的多个防护对象ID", example = "1,2,3,4")
+            }
+    )
    ResponseResult deleteProtectObject(@PathVariable List<Integer> protectObjectIds);

    @GetMapping("/{protectObjectId}/audit/{auditStatus}")
+    @Operation(
+            summary = "修改防护对象审核状态",
+            description = "修改指定防护对象ID对应的防护对象的审核状态",
+            responses = {
+                    @ApiResponse(
+                            description = "防护对象审核状态修改情况",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "protectObjectId", description = "欲修改的防护对象ID", example = "2"),
+                    @Parameter(name = "auditStatus", description = "欲修改的审核状态", example = "2")
+            }
+    )
    ResponseResult changeProtectObjectAuditStatus(@PathVariable Integer protectObjectId,
                                                  @PathVariable Integer auditStatus);
 }
--- a/src/main/java/com/realtime/protection/server/defense/template/TemplateController.java
+++ b/src/main/java/com/realtime/protection/server/defense/template/TemplateController.java
@@ -11,7 +11,7 @@ import java.util.List;

@RestController
@RequestMapping("/template")
-public class TemplateController {
+public class TemplateController implements TemplateControllerApi {

    private final TemplateService templateService;

@@ -19,6 +19,7 @@ public class TemplateController {
        this.templateService = templateService;
    }

+    @Override
    @PostMapping("/new")
    public ResponseResult newTemplate(@RequestBody @Valid Template template) {

@@ -35,6 +36,7 @@ public class TemplateController {
                .setData("success", false);
    }

+    @Override
    @GetMapping("/query")
    public ResponseResult queryTemplates(@RequestParam(value = "template_name", required = false) String templateName,
                                         @RequestParam("page") @Min(1) Integer page,
@@ -45,12 +47,19 @@ public class TemplateController {
                .setData("templates", templates);
    }

+    @Override
    @GetMapping("/{templateId}/query")
    public ResponseResult queryTemplate(@PathVariable Integer templateId) throws IllegalAccessException {
+        Template template = templateService.queryTemplate(templateId);
+        if (template == null) {
+            return ResponseResult.invalid()
+                    .setMessage("invalid templateId, maybe this template doesn't exist?");
+        }
        return ResponseResult.ok()
-                .setDataMap(EntityUtils.entityToMap(templateService.queryTemplate(templateId)));
+                .setDataMap(EntityUtils.entityToMap(template));
    }

+    @Override
    @PostMapping("/{templateId}/update")
    public ResponseResult updateTemplate(@PathVariable @Min(1) Integer templateId,
                                         @RequestBody @Valid Template template) {
@@ -60,6 +69,7 @@ public class TemplateController {
                .setData("success", success);
    }

+    @Override
    @DeleteMapping("/{templateId}/delete")
    public ResponseResult deleteTemplate(@PathVariable @Min(1) Integer templateId) {
        return ResponseResult.ok()
--- a/src/main/java/com/realtime/protection/server/defense/template/TemplateControllerApi.java
+++ b/src/main/java/com/realtime/protection/server/defense/template/TemplateControllerApi.java
@@ -0,0 +1,114 @@
+package com.realtime.protection.server.defense.template;
+
+import com.realtime.protection.configuration.entity.defense.template.Template;
+import com.realtime.protection.configuration.response.ResponseResult;
+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.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.Min;
+import org.springframework.web.bind.annotation.*;
+
+@Tag(name = "防御策略模板API", description = "防御策略模板模块所有接口")
+public interface TemplateControllerApi {
+    @PostMapping("/new")
+    @Operation(
+            summary = "新建防御策略模板",
+            description = "根据信息新建一个防护策略模板",
+            responses = {
+                    @ApiResponse(
+                            description = "返回新建防御策略模板结果",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "防御策略模板信息")
+    )
+    ResponseResult newTemplate(@RequestBody @Valid Template template);
+
+    @GetMapping("/query")
+    @Operation(
+            summary = "查询多个防御策略模板",
+            description = "根据查询条件查询多个防御策略模板",
+            responses = {
+                    @ApiResponse(
+                            description = "返回所有查询到的防御策略模板",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "template_name", description = "防御策略模板名称", example = "DDOS"),
+                    @Parameter(name = "page", description = "页码", example = "1"),
+                    @Parameter(name = "page_size", description = "每页对象数量", example = "5")
+            }
+    )
+    ResponseResult queryTemplates(@RequestParam(value = "template_name", required = false) String templateName,
+                                  @RequestParam("page") @Min(1) Integer page,
+                                  @RequestParam("page_size") @Min(1) Integer pageSize);
+
+    @GetMapping("/{templateId}/query")
+    @Operation(
+            summary = "查询单个防御策略模板",
+            description = "根据模板ID查询单个防御策略模板信息",
+            responses = {
+                    @ApiResponse(
+                            description = "返回单个防御策略模板信息",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "templateId", description = "防御策略模板ID", example = "5")
+            }
+    )
+    ResponseResult queryTemplate(@PathVariable Integer templateId) throws IllegalAccessException;
+
+    @PostMapping("/{templateId}/update")
+    @Operation(
+            summary = "更新防御策略模板信息",
+            description = "根据提供的防御策略模板信息更新指定ID对应的防御策略模板",
+            responses = {
+                    @ApiResponse(
+                            description = "返回防御策略模板信息更新结果",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "templateId", description = "防御策略模板ID", example = "5")
+            }
+    )
+    ResponseResult updateTemplate(@PathVariable @Min(1) Integer templateId,
+                                  @RequestBody @Valid Template template);
+
+    @DeleteMapping("/{templateId}/delete")
+    @Operation(
+            summary = "删除防御策略模板信息",
+            description = "根据策略模板ID删除指定的防御策略模板信息",
+            responses = {
+                    @ApiResponse(
+                            description = "返回防御策略模板删除结果",
+                            content = @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ResponseResult.class)
+                            )
+                    )
+            },
+            parameters = {
+                    @Parameter(name = "templateId", description = "防御策略模板ID", example = "5")
+            }
+    )
+    ResponseResult deleteTemplate(@PathVariable @Min(1) Integer templateId);
+}