feat: swagger文档配置

luoo_common/src/main/java/entity/ResultVO.java

@@ -0,0 +1,62 @@
+package entity;
+
+public class ResultVO<T>{
+
+
+	private boolean flag;
+	private Integer code;
+	private String message;
+	private T data;
+
+	public ResultVO() {
+	}
+
+	public ResultVO(boolean flag, Integer code, String message, T data) {
+		super();
+		this.flag = flag;
+		this.code = code;
+		this.message = message;
+		this.data = data;
+	}
+
+	public ResultVO(boolean flag, Integer code, String message) {
+		super();
+		this.flag = flag;
+		this.code = code;
+		this.message = message;
+	}
+	
+	public boolean isFlag() {
+		return flag;
+	}
+	public void setFlag(boolean flag) {
+		this.flag = flag;
+	}
+	public Integer getCode() {
+		return code;
+	}
+	public void setCode(Integer code) {
+		this.code = code;
+	}
+	public String getMessage() {
+		return message;
+	}
+	public void setMessage(String message) {
+		this.message = message;
+	}
+	public Object getData() {
+		return data;
+	}
+	public void setData(T data) {
+		this.data = data;
+	}
+	
+	public static <E> ResultVO<E> success(E data){
+		return new ResultVO<>(true,200,"操作成功", data);
+	}
+
+	public static ResultVO<Void> success(String message){
+		return new ResultVO<>(true,200,message);
+	}
+	
+}

luoo_tag/src/main/java/com/luoo/tag/controller/TagController.java

@@ -1,12 +1,18 @@
 package com.luoo.tag.controller;
 
 import com.luoo.tag.pojo.TagCreateReq;
+import com.luoo.tag.pojo.TagDTO;
 import com.luoo.tag.pojo.TagQueryReq;
 import com.luoo.tag.pojo.TagUpdateReq;
 import com.luoo.tag.service.TagService;
 import entity.Result;
+import entity.ResultVO;
 import entity.StatusCode;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
@@ -17,43 +23,91 @@ import java.util.Map;
  */
 @RestController
 @CrossOrigin
+@Tag(name = "标签API")
 @RequestMapping("/tag")
 @RequiredArgsConstructor
 public class TagController {
     private final TagService tagService;
 
+    @Operation(
+            description = "查询标签列表",
+            summary = "查询标签列表",
+            parameters = {
+                    @Parameter(name = "queryReq", description = "查询参数", required = true),
+                    @Parameter(name = "pageNum", description = "页码", required = true),
+                    @Parameter(name = "pageSize", description = "每页数", required = true)
+            }
+    )
     @GetMapping("/list")
-    public Result getById(@Validated @RequestBody TagQueryReq queryReq, @RequestParam int pageNum, @RequestParam int pageSize){
-        return new Result(true, StatusCode.OK, "查询成功", tagService.queryPage(queryReq, pageNum, pageSize));
+    public ResultVO<Page<TagDTO>> getById(@Validated @RequestBody TagQueryReq queryReq,
+                                          @RequestParam int pageNum, @RequestParam int pageSize){
+        return ResultVO.success(tagService.queryPage(queryReq, pageNum, pageSize));
     }
 
+    @Operation(
+            description = "查询标签详情",
+            summary = "查询标签详情",
+            parameters = {
+                    @Parameter(name = "id", description = "标签ID", required = true)
+            }
+    )
     @GetMapping("/{id}")
-    public Result getById(@PathVariable String id){
-        return new Result(true, StatusCode.OK, "查询成功", tagService.queryById(id));
+    public ResultVO<TagDTO> getById(@PathVariable String id){
+        return ResultVO.success(tagService.queryById(id));
     }
 
+    @Operation(
+            description = "新增标签信息",
+            summary = "新增标签信息",
+            parameters = {
+                    @Parameter(name = "createReq", description = "创建参数", required = true)
+            }
+    )
     @PostMapping
-    public Result create(@Validated @RequestBody TagCreateReq createReq){
+    public ResultVO<Void> create(@Validated @RequestBody TagCreateReq createReq){
         tagService.create(createReq);
-        return new Result(true, StatusCode.OK, "创建成功");
+        return ResultVO.success("创建成功");
     }
 
+    @Operation(
+            description = "更新标签信息",
+            summary = "更新标签信息",
+            parameters = {
+                    @Parameter(name = "updateReq", description = "更新参数", required = true),
+                    @Parameter(name = "id", description = "标签ID", required = true)
+            }
+    )
     @PutMapping("/{id}")
-    public Result update(@Validated @RequestBody TagUpdateReq updateReq, @PathVariable String id){
+    public ResultVO<Void> update(@Validated @RequestBody TagUpdateReq updateReq, @PathVariable String id){
         updateReq.setId(id);
         tagService.update(updateReq);
-        return new Result(true, StatusCode.OK, "更新成功");
+        return ResultVO.success("更新成功");
     }
 
+    @Operation(
+            description = "更新标签状态",
+            summary = "更新标签状态",
+            parameters = {
+                    @Parameter(name = "id", description = "标签ID", required = true),
+                    @Parameter(name = "state", description = "标签状态", required = true)
+            }
+    )
     @PutMapping("/status/{id}")
-    public Result updateStatus(@PathVariable String id, @RequestParam Integer state){
+    public ResultVO<Void> updateStatus(@PathVariable String id, @RequestParam Integer state){
         tagService.updateState(id, state);
-        return new Result(true, StatusCode.OK,"状态更新成功");
+        return ResultVO.success("状态更新成功");
     }
 
+    @Operation(
+            description = "删除标签",
+            summary = "删除标签",
+            parameters = {
+                    @Parameter(name = "id", description = "标签ID", required = true)
+            }
+    )
     @DeleteMapping("/{id}")
-    public Result delete(@PathVariable String id){
+    public ResultVO<Void> delete(@PathVariable String id){
         tagService.delete(id);
-        return new Result(true, StatusCode.OK,"删除成功");
+        return ResultVO.success("删除成功");
     }
 }

luoo_tag/src/main/java/com/luoo/tag/pojo/TagCreateReq.java

@@ -1,5 +1,6 @@
 package com.luoo.tag.pojo;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import javax.validation.constraints.NotBlank;
@@ -9,17 +10,21 @@ import java.io.Serializable;
  * 标签创建请求参数
  */
 @Data
+@Schema(description = "标签创建请求")
 public class TagCreateReq implements Serializable {
     private static final long serialVersionUID = -3431829126574541980L;
 
     /**
      * 父标签ID
      */
+    @Schema(description = "父标签ID")
     private String parentId = "";
 
+    @Schema(description = "标签中文名")
     @NotBlank(message = "标签中文名称必填")
     private String nameCh;
 
+    @Schema(description = "标签英文名")
     @NotBlank(message = "标签英文名称必填")
     private String nameEn;
 }

luoo_tag/src/main/java/com/luoo/tag/pojo/TagDTO.java

@@ -1,35 +1,48 @@
 package com.luoo.tag.pojo;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.io.Serializable;
 import java.time.LocalDateTime;
 
 @Data
+@Schema(description = "标签DTO")
 public class TagDTO implements Serializable {
     private static final long serialVersionUID = -1198060864891902188L;
 
+    @Schema(description = "标签ID")
     private String id;
 
+    @Schema(description = "父标签ID")
     private String parentId;
 
+    @Schema(description = "父标签名称")
     private String parentNameCh;
 
+    @Schema(description = "标签中文名称")
     private String nameCh;
 
+    @Schema(description = "标签英文名称")
     private String nameEn;
 
+    @Schema(description = "标签状态 0=禁用，1=启用")
     private Integer state;
 
+    @Schema(description = "子标签数量")
     private Long childTagCount = 0L;
 
+    @Schema(description = "关联文章数量")
     private Long articleRefCount = 0L;
 
+    @Schema(description = "关联歌曲数量")
     private Long songRefCount = 0L;
 
+    @Schema(description = "创建人")
     private String creatorName;
 
+    @Schema(description = "创建时间")
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     private LocalDateTime createTime;
 }

luoo_tag/src/main/java/com/luoo/tag/pojo/TagQueryReq.java

@@ -1,6 +1,7 @@
 package com.luoo.tag.pojo;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import javax.validation.constraints.NotNull;
@@ -11,26 +12,32 @@ import java.time.LocalDateTime;
  * 标签列表查询参数
  */
 @Data
+@Schema(description = "标签列表查询请求")
 public class TagQueryReq implements Serializable {
     private static final long serialVersionUID = -1198060864891902188L;
 
     @NotNull(message = "标签层级不能为空：1=一级，2=二级")
+    @Schema(description = "标签层级 1=一级，2=二级")
     private Integer level;
 
+    @Schema(description = "标签ID")
     private String id;
 
+    @Schema(description = "父标签ID")
     private String parentId;
 
-    /**
-     * 标签中英文名
-     */
+    @Schema(description = "标签名称")
     private String name;
 
+    @Schema(description = "标签状态 0=禁用，1=启用")
     private Integer state;
 
+    @Schema(description = "创建人ID")
     private String creatorId;
 
+    @Schema(description = "创建时间-开始")
     private LocalDateTime createTimeStart;
 
+    @Schema(description = "创建时间-结束")
     private LocalDateTime createTimeEnd;
 }

luoo_tag/src/main/java/com/luoo/tag/pojo/TagUpdateReq.java

@@ -1,5 +1,6 @@
 package com.luoo.tag.pojo;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
@@ -11,14 +12,18 @@ import java.io.Serializable;
  * 标签更新请求参数
  */
 @Data
+@Schema(description = "标签更新请求")
 public class TagUpdateReq implements Serializable {
     private static final long serialVersionUID = -8810544476079524714L;
 
+    @Schema(description = "标签ID")
     private String id;
 
+    @Schema(description = "标签中文名")
     @NotBlank(message = "标签中文名称必填")
     private String nameCh;
 
+    @Schema(description = "标签英文名")
     @NotBlank(message = "标签英文名称必填")
     private String nameEn;
 }