优化api接口文档

pom.xml

@@ -35,6 +35,13 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>com.github.xiaoymin</groupId>
+                <artifactId>knife4j-dependencies</artifactId>
+                <version>4.5.0</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -141,22 +148,8 @@
         <dependency>
             <groupId>com.github.xiaoymin</groupId>
             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
-            <version>4.4.0</version>
+<!--            <version>4.4.0</version>-->
         </dependency>
-        <!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
-<!--        <dependency>-->
-<!--            <groupId>io.swagger.core.v3</groupId>-->
-<!--            <artifactId>swagger-annotations</artifactId>-->
-<!--            <version>2.2.19</version>-->
-<!--        </dependency>-->
-
-        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-annotations -->
-        <dependency>
-            <groupId>io.swagger</groupId>
-            <artifactId>swagger-annotations</artifactId>
-            <version>1.6.14</version>
-        </dependency>
-
         <dependency>
             <groupId>com.fasterxml.jackson.datatype</groupId>
             <artifactId>jackson-datatype-jsr310</artifactId>

src/main/java/com/sckw/freight/config/SwaggerConfig.java

@@ -0,0 +1,28 @@
+package com.sckw.freight.config;
+
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/***
+ * 创建Swagger配置
+ * @since:knife4j-springdoc-openapi-demo 1.0
+ * @author <a href="mailto:xiaoymin@foxmail.com">xiaoymin@foxmail.com</a>
+ * 2020/03/15 20:40
+ */
+@Configuration
+public class SwaggerConfig {
+    @Bean
+    public OpenAPI customOpenAPI() {
+        return new OpenAPI()
+                .info(new Info()
+                        .title("数货运结-对账结算API")
+                        .version("1.0")
+                        .description("数货运结-对账结算API")
+                       );
+    }
+
+
+}

src/main/java/com/sckw/freight/controller/LedgerController.java

@@ -1,7 +1,5 @@
 package com.sckw.freight.controller;
 
-import com.github.xiaoymin.knife4j.annotations.DynamicParameter;
-import com.github.xiaoymin.knife4j.annotations.DynamicResponseParameters;
 import com.sckw.freight.model.vo.request.RequestLedgerLogisticsPageInfo;
 import com.sckw.freight.model.vo.request.RequestSaveLedgerLogisticsInfo;
 import com.sckw.freight.model.vo.response.ResponseKllOrderTask;
@@ -10,6 +8,8 @@ import com.sckw.freight.model.vo.response.ResponsePageData;
 import com.sckw.freight.service.freight.IKwpLedgerLogisticsService;
 import com.sckw.freight.util.R;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -62,9 +62,9 @@ public class LedgerController {
      */
     @GetMapping("/queryOrderTaskListByLedgerLogisticsId")
     @Operation(summary = "根据对账单id查询运单列表信息")
-    @DynamicResponseParameters(name = "queryOrderTaskListByLedgerLogisticsId", properties = {
-            @DynamicParameter(name = "ledgerLogisticsId", value = "对账单id"),
-            @DynamicParameter(name = "entId", value = "企业id"),
+    @Parameters(value = {
+            @Parameter(name = "ledgerLogisticsId", description = "对账单id"),
+            @Parameter(name = "entId", description = "企业id")
     })
     public R<List<ResponseKllOrderTask>> queryOrderTaskListByLedgerLogisticsId(
             @RequestParam(value = "ledgerLogisticsId", required = true) Long ledgerLogisticsId,

src/main/java/com/sckw/freight/controller/SettlementLogisticsController.java

@@ -1,13 +1,13 @@
 package com.sckw.freight.controller;
 
-import com.github.xiaoymin.knife4j.annotations.DynamicParameter;
-import com.github.xiaoymin.knife4j.annotations.DynamicResponseParameters;
 import com.sckw.freight.model.vo.request.RequestSettlementLogisticsPageInfo;
 import com.sckw.freight.model.vo.response.ResponsePageData;
 import com.sckw.freight.model.vo.response.ResponseSettlementLogistics;
 import com.sckw.freight.service.freight.IKwpSettlementLogisticsService;
 import com.sckw.freight.util.R;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -42,12 +42,12 @@ public class SettlementLogisticsController {
      **/
     @GetMapping("/add")
     @Operation(summary = "添加收款")
-    @DynamicResponseParameters(name = "addSettlementLogistics", properties = {
-            @DynamicParameter(name = "lLedgerId", value = "对账单id"),
-            @DynamicParameter(name = "price", value = "付款金额"),
-            @DynamicParameter(name = "slOrderNo", value = "付款单号"),
-            @DynamicParameter(name = "payTime", value = "支付时间"),
-            @DynamicParameter(name = "userid", value = "用户id"),
+    @Parameters(value = {
+            @Parameter(name = "lLedgerId", description = "对账单id"),
+            @Parameter(name = "price", description = "付款金额"),
+            @Parameter(name = "slOrderNo", description = "付款单号"),
+            @Parameter(name = "payTime", description = "支付时间"),
+            @Parameter(name = "userid", description = "用户id"),
     })
     public R<String> addSettlementLogistics(
             @RequestParam(value = "lLedgerId", required = true)Long lLedgerId,

src/main/java/com/sckw/freight/model/enums/SettlementLogisticsStatusEnum.java

@@ -18,9 +18,9 @@ import java.util.stream.Collectors;
 @AllArgsConstructor
 public enum SettlementLogisticsStatusEnum {
 
-    ToSettled(1, "待结算"),
-    PartialSettlement (2, "部分结算"),
-    FullSettlement (3, "全部结算");
+//    ToSettled(1, "待结算"),
+//    PartialSettlement (2, "部分结算"),
+    FullSettlement (3, "已付款");
     private final Integer code;
     private final String msg;
 

src/main/java/com/sckw/freight/model/vo/request/RequestLedgerLogisticsPageInfo.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.request;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.time.LocalDateTime;
@@ -15,38 +14,39 @@ import java.time.LocalDateTime;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "物流对账单-分页查询参数",description = "物流对账单-分页查询参数")
+@Schema(description = "物流对账单-分页查询参数")
 public class RequestLedgerLogisticsPageInfo extends RequestPageInfo {
 
     /**
      * 物流对账单编号
      */
-    @ApiModelProperty(value = "物流对账单编号")
+    @Schema(description = "物流对账单编号")
+    //@ApiModelProperty(value = "物流对账单编号")
     private String lLedgerNo;
 
     /**
      * 对账单名称
      */
-    @ApiModelProperty(value = "对账单名称")
+    @Schema(description = "对账单名称")
     private String name;
     /**
      * 对账单状态
      */
-    @ApiModelProperty(value = "对账单状态", allowableValues = "0-待支付，1-部分支付，2-已支付")
+    @Schema(description = "对账单状态", allowableValues = "0-待支付，1-部分支付，2-已支付")
     private Integer status;
     /**
      * 创建时间 ["2025-01-09","2025-01-09"]
      */
-    @ApiModelProperty(value = "创建时间", allowableValues = "[2025-01-09,2025-01-09]")
+    @Schema(description = "创建时间", allowableValues = "[2025-01-09,2025-01-09]")
     private LocalDateTime[] createTime;
     /**
      * 更新时间 ["2025-01-09","2025-01-09"]
      */
-    @ApiModelProperty(value = "更新时间", allowableValues = "[2025-01-09,2025-01-09]")
+    @Schema(description="更新时间",  allowableValues = "[2025-01-09,2025-01-09]")
     private LocalDateTime[] updateTime;
     /**
      * 企业id
      */
-    @ApiModelProperty(value = "企业id")
+    @Schema(description = "企业id")
     private Long entId;
 }

src/main/java/com/sckw/freight/model/vo/request/RequestPageInfo.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.request;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 /**
  * @BelongsProject: Freight-Settlement-Backend
@@ -12,27 +11,27 @@ import lombok.Data;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "分页查询参数",description = "分页查询参数")
+@Schema( description = "分页查询参数")
 public class RequestPageInfo {
     private static final long serialVersionUID = 1L;
     /**
      * 当前页码
      */
-    @ApiModelProperty(value = "当前页码",allowableValues = "1,2,3,4,5",example = "1")
+    @Schema(description = "当前页码",allowableValues = "1,2,3,4,5",example = "1")
     private long page=1;
     /**
      * 每页数量
      */
-    @ApiModelProperty(value = "每页数量",allowableValues = "1,10,20,50,100")
+    @Schema(description = "每页数量",allowableValues = "1,10,20,50,100")
     private long pageSize=10;
     /**
      * 排序字段
      */
-    @ApiModelProperty(value = "排序字段")
+    @Schema(description = "排序字段")
     private String sortField;
     /**
      * 排序方式
      */
-    @ApiModelProperty(value = "排序方式", allowableValues = "asc,desc")
+    @Schema(description = "排序方式", allowableValues = "asc,desc")
     private String sortOrder;
 }

src/main/java/com/sckw/freight/model/vo/request/RequestSaveLedgerLogisticsInfo.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.request;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.math.BigDecimal;
@@ -16,37 +15,37 @@ import java.util.List;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "新建对账单信息",description = "新建对账单信息")
+@Schema(description = "新建对账单信息")
 public class RequestSaveLedgerLogisticsInfo {
     /**
      * 物流订单ID
      */
-    @ApiModelProperty(value = "物流订单ID",allowableValues ="[123,234]" )
+    @Schema(description = "物流订单ID",allowableValues ="[123,234]" )
     private List<Long> orderIds;
     /**
      * 对账单名称
      */
-    @ApiModelProperty(value = "对账单名称" )
+    @Schema(description = "对账单名称" )
     private String name;
     /**
      * 扣款金额
      */
-    @ApiModelProperty(value = "扣款金额" )
+    @Schema(description = "扣款金额" )
     private BigDecimal deductPrice;
     /**
      * 企业id
      */
-    @ApiModelProperty(value = "企业id" )
+    @Schema(description = "企业id" )
     private Long entId;
     /**
      * 备注
      */
-    @ApiModelProperty(value = "备注" )
+    @Schema(description = "备注" )
     private String remark;
     /**
      * 当前登录用户id
      */
-    @ApiModelProperty(value = "当前登录用户id" )
+    @Schema(description = "当前登录用户id" )
     private Long userId;
 
 }

src/main/java/com/sckw/freight/model/vo/request/RequestSettlementLogisticsPageInfo.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.request;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.time.LocalDateTime;
@@ -16,12 +15,12 @@ import java.util.List;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "物流对账单-收款记录-分页查询参数", description = "物流对账单-收款记录-分页查询参数")
+@Schema( description = "物流对账单-收款记录-分页查询参数")
 public class RequestSettlementLogisticsPageInfo extends RequestPageInfo {
-    @ApiModelProperty(value = "对账单 id")
+    @Schema(description = "对账单 id")
     private Long lLedgerId;
-    @ApiModelProperty(value = "收款单号")
+    @Schema(description = "收款单号")
     private String slOrderNo;
-    @ApiModelProperty(value = "收款时间", allowableValues = "[2025-01-09,2025-01-09]")
+    @Schema(description = "收款时间", allowableValues = "[2025-01-09,2025-01-09]")
     private List<LocalDateTime> payTime;
 }

src/main/java/com/sckw/freight/model/vo/response/ResponseKllOrderTask.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.response;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.math.BigDecimal;
@@ -15,25 +14,25 @@ import java.math.BigDecimal;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "运单信息")
+@Schema(description = "运单信息")
 public class ResponseKllOrderTask {
     private static final long serialVersionUID = 1L;
 
     /**
      * 运单ID
      */
-    @ApiModelProperty(value = "运单ID")
+    @Schema(description = "运单ID")
     private Integer id;
     /**
      * 运单号
      */
-    @ApiModelProperty(value = "运单号")
+    @Schema(description = "运单号")
     private String taskNo;
 
     /**
      * 订单ID
      */
-    @ApiModelProperty(value = "物流订单ID")
+    @Schema(description = "物流订单ID")
     private Integer orderId;
 
     /**
@@ -50,7 +49,7 @@ public class ResponseKllOrderTask {
     /**
      * 卡车车牌
      */
-    @ApiModelProperty(value = "卡车车牌")
+    @Schema(description = "卡车车牌")
     private String truckLicensePlate;
 
     /**
@@ -82,13 +81,13 @@ public class ResponseKllOrderTask {
     /**
      * 卡车司机名
      */
-    @ApiModelProperty(value = "卡车司机名")
+    @Schema(description = "卡车司机名")
     private String driverName;
 
     /**
      * 卡车司机电话
      */
-    @ApiModelProperty(value = "卡车司机电话")
+    @Schema(description = "卡车司机电话")
     private String driverPhone;
 
     /**
@@ -119,7 +118,7 @@ public class ResponseKllOrderTask {
     /**
      * 首次称重
      */
-    @ApiModelProperty(value = "装货量")
+    @Schema(description = "装货量")
     private BigDecimal firstWeight;
 
     /**
@@ -130,6 +129,6 @@ public class ResponseKllOrderTask {
     /**
      * 二次称重
      */
-    @ApiModelProperty(value = "卸货量")
+    @Schema(description = "卸货量")
     private BigDecimal secondWeight;
 }

src/main/java/com/sckw/freight/model/vo/response/ResponseLedgerLogistics.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.response;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.math.BigDecimal;
@@ -15,64 +14,64 @@ import java.math.BigDecimal;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "物流对账单信息")
+@Schema(description = "物流对账单信息")
 public class ResponseLedgerLogistics {
     /**
      * 主键
      */
-    @ApiModelProperty(value = "物流对账单id")
+    @Schema(description = "物流对账单id")
     private Long id;
     /**
      * 物流对账单编号
      */
-    @ApiModelProperty(value = "物流对账单编号")
+    @Schema(description = "物流对账单编号")
     private String lLedgerNo;
 
     /**
      * 对账单名称
      */
-    @ApiModelProperty(value = "对账单名称")
+    @Schema(description = "对账单名称")
     private String name;
 
     /**
      * 4.0 状态（1-已保存、2-待对账、3-已对账、4-已完成、5-已退回 6-已撤回）
      * 数货运结 (1-待支付，2-部分支付，3-已支付)
      */
-    @ApiModelProperty(value = "物流对账单状态")
+    @Schema(description = "物流对账单状态")
     private Integer status;
     /**
      * 状态名称
      */
-    @ApiModelProperty(value = "物流对账单状态名称")
+    @Schema(description = "物流对账单状态名称")
     private String statusName;
     /**
      * 支付比例
      */
-    @ApiModelProperty(value = "支付比例")
+    @Schema(description = "支付比例")
     private String payRatio;
     /**
      * 已收款/元
      */
-    @ApiModelProperty(value = "已收款/元")
+    @Schema(description = "已收款/元")
     private BigDecimal actualPrice;
     /**
      * 总应收/元
      */
-    @ApiModelProperty(value = "账单总金额")
+    @Schema(description = "账单总金额")
     private BigDecimal totalPrice;
     /**
      * 创建时间
      */
-    @ApiModelProperty(value = "创建时间")
+    @Schema(description = "创建时间")
     private String createTime;
     /**
      * 更新时间
      */
-    @ApiModelProperty(value = "更新时间")
+    @Schema(description = "更新时间")
     private String updateTime;
     /**
      * 备注
      */
-    @ApiModelProperty(value = "备注")
+    @Schema(description = "备注")
     private String remark;
 }

src/main/java/com/sckw/freight/model/vo/response/ResponsePageData.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.response;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.util.List;
@@ -15,32 +14,32 @@ import java.util.List;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "分页数据")
+@Schema(description = "分页数据")
 public class ResponsePageData<T> {
     private static final long serialVersionUID = 7367318386929321066L;
     /**
      * 当前页码
      */
-    @ApiModelProperty(value = "当前页码")
+    @Schema(description = "当前页码")
     private long page;
     /**
      * 每页数量
      */
-    @ApiModelProperty(value = "每页数量")
+    @Schema(description = "每页数量")
     private long pageSize;
     /**
      * 总页数
      */
-    @ApiModelProperty(value = "总页数")
+    @Schema(description = "总页数")
     private long pages;
     /**
      *总条数
      */
-    @ApiModelProperty(value = "总条数")
+    @Schema(description = "总条数")
     private long total;
     /**
      * 数据列表
      */
-    @ApiModelProperty(value = "数据列表")
+    @Schema(description = "数据列表")
     private List<T> list;
 }

src/main/java/com/sckw/freight/model/vo/response/ResponseSettlementLogistics.java

@@ -1,7 +1,6 @@
 package com.sckw.freight.model.vo.response;
 
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.math.BigDecimal;
@@ -15,60 +14,60 @@ import java.math.BigDecimal;
  * @Version: 1.0
  */
 @Data
-@ApiModel(value = "物流对账单-付款记录")
+@Schema(description = "物流对账单-付款记录")
 public class ResponseSettlementLogistics {
 
     /**
      * 主键
      */
-    @ApiModelProperty(value = "主键")
+    @Schema(description = "主键")
     private Long id;
 
     /**
      * 企业id
      */
-    @ApiModelProperty(value = "企业id")
+    @Schema(description = "企业id")
     private Long entId;
 
     /**
      * 物流订单对账id
      */
-    @ApiModelProperty(value = "物流订单对账id")
+    @Schema(description = "物流订单对账id")
     private Long lLedgerId;
 
     /**
      * 付款单号
      */
-    @ApiModelProperty(value = "付款单号")
+    @Schema(description = "付款单号")
     private String slOrderNo;
 
     /**
      * 对账金额
      */
-    @ApiModelProperty(value = "对账金额")
+    @Schema(description = "对账金额")
     private BigDecimal totalPrice;
 
     /**
      * 收款日期
      */
-    @ApiModelProperty(value = "收款日期")
+    @Schema(description = "收款日期")
     private String receiptTime;
     /**
      * 生成日期
      */
-    @ApiModelProperty(value = "生成日期")
+    @Schema(description = "生成日期")
     private String createdTime;
 
     /**
      * 备注
      */
-    @ApiModelProperty(value = "备注")
+    @Schema(description = "备注")
     private String remark;
 
     /**
      * 状态（1待结算2部分结算3全部结算）
      */
     private Integer status;
-    @ApiModelProperty(value = "状态（1待结算2部分结算3全部结算）")
+    @Schema(description = "状态（1待结算2部分结算3全部结算）")
     private String statusName;
 }

src/main/java/com/sckw/freight/util/R.java

@@ -1,6 +1,6 @@
 package com.sckw.freight.util;
 
-import io.swagger.annotations.ApiModelProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.*;
 import lombok.experimental.Accessors;
 
@@ -21,16 +21,16 @@ public class R<T> implements Serializable {
 
     @Getter
     @Setter
-    @ApiModelProperty(value = "返回信息")
+    @Schema(description = "返回信息")
     private String msg;
     @Getter
     @Setter
-    @ApiModelProperty(value = "返回状态")
+    @Schema(description = "返回状态")
     private Boolean status;
 
     @Getter
     @Setter
-    @ApiModelProperty(value = "返回数据")
+    @Schema(description = "返回数据")
     private T data;
 
     public static <T> R<T> ok() {

src/main/resources/application-dev.yml

@@ -43,20 +43,6 @@ mybatis-plus:
     log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
 
 # 生产环境不需要配置
-# springdoc-openapi项目配置
-springdoc:
-  swagger-ui:
-    path: /swagger-ui.html
-    tags-sorter: alpha
-    operations-sorter: alpha
-  api-docs:
-    path: /v3/api-docs
-    version: openapi_3_1
-  group-configs:
-    - group: 'default'
-      paths-to-match: '/**'
-      packages-to-scan: com.sckw.freight.controller
-
 # knife4j的增强配置，不需要增强可以不配
 knife4j:
   enable: true