feat(swagger): 升级Swagger至OpenAPI3并更新相关注解

2025-10-31 10:36:13 +08:00
parent 55f9846b17
commit 075764785e
105 changed files with 564 additions and 603 deletions
@@ -16,11 +16,10 @@

 package cn.odboy.base;

+import jakarta.validation.constraints.NotNull;
 import lombok.Getter;
 import lombok.Setter;

-import jakarta.validation.constraints.NotNull;
-
 /**
 * 通用参数
 *
@@ -18,7 +18,7 @@ package cn.odboy.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -29,7 +29,7 @@ import java.util.Date;
@Setter
@EqualsAndHashCode(callSuper = false)
 public class CsBaseCreateTimeTb extends CsObject {
+    @Schema(name ="创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date createTime;
 }
@@ -18,7 +18,7 @@ package cn.odboy.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -30,10 +30,10 @@ import java.util.Date;
@EqualsAndHashCode(callSuper = false)
 public class CsBaseTimeTb extends CsObject {
    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
+    @Schema(name = "创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
+    @Schema(name = "更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date updateTime;
 }
@@ -18,7 +18,7 @@ package cn.odboy.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -29,7 +29,7 @@ import java.util.Date;
@Setter
@EqualsAndHashCode(callSuper = false)
 public class CsBaseUpdateTimeTb extends CsObject {
+    @Schema(name ="更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    @TableField(fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date updateTime;
 }
@@ -18,7 +18,7 @@ package cn.odboy.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -35,11 +35,11 @@ public class CsBaseUserCreateTimeTb extends CsObject {

    @CreatedBy
    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建人", hidden = true)
+    @Schema(name ="创建人", hidden = true)
    private String createBy;

    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
+    @Schema(name ="创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date createTime;

    /* 分组校验 */
@@ -19,7 +19,7 @@ package cn.odboy.base;
 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
 import com.baomidou.mybatisplus.annotation.TableLogic;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 import lombok.Setter;
 import org.springframework.data.annotation.CreatedBy;
@@ -38,19 +38,19 @@ import java.util.Date;
 public class CsBaseUserTimeLogicTb extends CsObject {
    @CreatedBy
    @TableField(value = "create_by", fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建人", hidden = true)
+    @Schema(name ="创建人", hidden = true)
    private String createBy;
    @LastModifiedBy
    @TableField(value = "update_by", fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新人", hidden = true)
+    @Schema(name ="更新人", hidden = true)
    private String updateBy;
    @TableField(value = "create_time", fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建时间", hidden = true)
+    @Schema(name ="创建时间", hidden = true)
    private Date createTime;
    @TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新时间", hidden = true)
+    @Schema(name ="更新时间", hidden = true)
    private Date updateTime;
-    @ApiModelProperty(value = "数据有效性", hidden = true)
+    @Schema(name ="数据有效性", hidden = true)
    @TableLogic
    @TableField("available")
    private Integer available;
@@ -18,7 +18,7 @@ package cn.odboy.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -36,20 +36,20 @@ public class CsBaseUserTimeTb extends CsObject {

    @CreatedBy
    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建人", hidden = true)
+    @Schema(name ="创建人", hidden = true)
    private String createBy;

    @LastModifiedBy
    @TableField(fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新人", hidden = true)
+    @Schema(name ="更新人", hidden = true)
    private String updateBy;

    @TableField(fill = FieldFill.INSERT)
-    @ApiModelProperty(value = "创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
+    @Schema(name ="创建时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
-    @ApiModelProperty(value = "更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
+    @Schema(name ="更新时间: yyyy-MM-dd HH:mm:ss", hidden = true)
    private Date updateTime;

    /* 分组校验 */
@@ -16,13 +16,13 @@

 package cn.odboy.base;

-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotNull;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;

-import jakarta.validation.constraints.Min;
-import jakarta.validation.constraints.NotNull;
 import java.io.Serializable;

 /**
@@ -37,11 +37,11 @@ import java.io.Serializable;
 public class CsPageArgs<T> implements Serializable {
    @NotNull(message = "参数page不能为空")
    @Min(value = 1, message = "参数page最小值为1")
-    @ApiModelProperty(value = "页码", example = "1")
+    @Schema(name ="页码", example = "1")
    private Integer page;
    @NotNull(message = "参数size不能为空")
    @Min(value = 1, message = "参数size最小值为1")
-    @ApiModelProperty(value = "每页数据量", example = "10")
+    @Schema(name ="每页数据量", example = "10")
    private Integer size;
    private T args;
 }
@@ -50,7 +50,7 @@ public class BootApplication {
                        "Application is running! Access URLs:\n\t" +
                    "Local: \t\thttp://localhost:" + port + path + "/\n\t" +
                    "External: \thttp://" + ip + ":" + port + path + "/\n\t"
-//                    + "Swagger文档: \thttp://" + ip + ":" + port + path + "/doc.html\n"
+                    + "Swagger文档: \thttp://" + ip + ":" + port + path + "/doc.html\n"
                    + "----------------------------------------------------------");
    }
 }
@@ -20,6 +20,7 @@ package cn.odboy.framework.context;
 import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.web.context.request.RequestContextHolder;
 import org.springframework.web.context.request.ServletRequestAttributes;
+
 import java.util.Objects;

 /**
@@ -18,7 +18,7 @@ package cn.odboy.framework.monitor.controller;

 import cn.odboy.annotation.AnonymousGetMapping;
 import cn.odboy.framework.monitor.service.CsHealthCheckPointService;
-import io.swagger.annotations.Api;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -29,7 +29,7 @@ import org.springframework.web.bind.annotation.RestController;
 */
@RestController
@RequestMapping("/healthCheck")
-@Api(tags = "系统：健康检查接口")
+@Tag(name = "系统：健康检查接口")
 public class HealthCheckController {
    @Autowired
    private CsHealthCheckPointService healthCheckPointService;
@@ -19,6 +19,9 @@ package cn.odboy.framework.mybatisplus.config;
 import com.alibaba.druid.spring.boot3.autoconfigure.DruidDataSourceAutoConfigure;
 import com.alibaba.druid.spring.boot3.autoconfigure.properties.DruidStatProperties;
 import com.alibaba.druid.util.Utils;
+import jakarta.servlet.*;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
 import org.springframework.boot.autoconfigure.AutoConfigureAfter;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
@@ -26,9 +29,6 @@ import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

-import jakarta.servlet.*;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
 import java.io.IOException;

@Configuration
@@ -28,8 +28,9 @@ import com.baomidou.mybatisplus.annotation.TableId;
 import com.baomidou.mybatisplus.annotation.TableName;
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 import jakarta.validation.constraints.NotBlank;
-import lombok.extern.slf4j.Slf4j;
 import jakarta.validation.constraints.NotNull;
+import lombok.extern.slf4j.Slf4j;
+
 import java.lang.reflect.Field;
 import java.util.*;
 import java.util.stream.Collectors;
@@ -20,7 +20,6 @@ import cn.hutool.core.util.StrUtil;
 import cn.odboy.base.CsObject;
 import cn.odboy.constant.CaptchaCodeEnum;
 import cn.odboy.framework.exception.BadRequestException;
-import cn.odboy.util.CsStringUtil;
 import com.wf.captcha.*;
 import com.wf.captcha.base.Captcha;
 import lombok.Getter;
@@ -21,7 +21,6 @@ import com.alibaba.fastjson2.JSONFactory;
 import com.alibaba.fastjson2.JSONWriter;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.codec.digest.MurmurHash3;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.autoconfigure.AutoConfigureBefore;
 import org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration;
 import org.springframework.cache.Cache;
@@ -31,7 +31,6 @@ import org.springframework.http.converter.StringHttpMessageConverter;
 import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 import org.springframework.web.filter.CorsFilter;
-
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@@ -17,12 +17,13 @@
 package cn.odboy.framework.websocket.context;

 import com.alibaba.fastjson2.JSON;
+import jakarta.websocket.*;
+import jakarta.websocket.server.PathParam;
 import jakarta.websocket.server.ServerEndpoint;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Component;
-import jakarta.websocket.*;
-import jakarta.websocket.server.PathParam;
+
 import java.io.IOException;
 import java.util.Map;
 import java.util.Objects;
@@ -18,10 +18,10 @@ package cn.odboy.util;

 import cn.hutool.http.useragent.UserAgent;
 import cn.hutool.http.useragent.UserAgentUtil;
+import jakarta.servlet.http.HttpServletRequest;
 import lombok.experimental.UtilityClass;
 import lombok.extern.slf4j.Slf4j;

-import jakarta.servlet.http.HttpServletRequest;
 import java.net.InetAddress;
 import java.net.UnknownHostException;

@@ -23,15 +23,15 @@ import cn.hutool.poi.excel.ExcelUtil;
 import cn.odboy.constant.FileTypeEnum;
 import cn.odboy.constant.SystemConst;
 import cn.odboy.framework.exception.BadRequestException;
+import jakarta.servlet.ServletOutputStream;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
 import lombok.experimental.UtilityClass;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.poi.util.IOUtils;
 import org.apache.poi.xssf.streaming.SXSSFSheet;
 import org.springframework.web.multipart.MultipartFile;

-import jakarta.servlet.ServletOutputStream;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
 import java.io.*;
 import java.nio.file.Files;
 import java.security.MessageDigest;
@@ -17,13 +17,13 @@
 package cn.odboy.util;

 import cn.odboy.framework.exception.BadRequestException;
-import lombok.experimental.UtilityClass;
-
 import jakarta.validation.ConstraintViolation;
 import jakarta.validation.Validation;
 import jakarta.validation.Validator;
 import jakarta.validation.ValidatorFactory;
 import jakarta.validation.groups.Default;
+import lombok.experimental.UtilityClass;
+
 import java.util.Set;
 import java.util.stream.Collectors;