在线接口文档

config/application-local.yaml

@@ -0,0 +1,17 @@
+# springdoc-openapi项目配置
+springdoc:
+  swagger-ui:
+    path: /swagger-ui.html
+    tags-sorter: alpha
+    operations-sorter: alpha
+  api-docs:
+    path: /v3/api-docs
+  group-configs:
+    - group: 'default'
+      paths-to-match: '/**'
+      packages-to-scan: com.zjyr.beidouservice
+# knife4j的增强配置，不需要增强可以不配
+knife4j:
+  enable: true
+  setting:
+    language: zh_cn

pom.xml

@@ -121,7 +121,12 @@
             <artifactId>mapstruct</artifactId>
             <version>1.5.3.Final</version>
         </dependency>
-    </dependencies>
+		<dependency>
+			<groupId>com.github.xiaoymin</groupId>
+			<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+			<version>4.3.0</version>
+		</dependency>
+	</dependencies>
 
 	<build>
 		<plugins>

src/main/java/com/zjyr/beidouservice/controller/DeviceController.java

@@ -6,6 +6,8 @@ import com.zjyr.beidouservice.pojo.dto.DeviceReqDTO;
 import com.zjyr.beidouservice.pojo.dto.DeviceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.DeviceSearchDTO;
 import com.zjyr.beidouservice.service.DeviceService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.validation.annotation.Validated;
@@ -21,6 +23,7 @@ import java.util.List;
 @RequestMapping("/")
 @Validated
 @Slf4j
+@Tag(name = "设备接口")
 public class DeviceController {
 
     @Resource
@@ -31,6 +34,7 @@ public class DeviceController {
      *
      * @return 设备列表
      */
+    @Operation(summary = "获取设备位置信息")
     @PostMapping("device/location")
     public MyResp<List<DeviceRespDTO>> getDeviceByLocation(@RequestBody DeviceReqDTO deviceReqDTO) {
         List<DeviceRespDTO> deviceRespDTO = deviceService.getDeviceByLocation(deviceReqDTO);
@@ -42,6 +46,7 @@ public class DeviceController {
      *
      * @return 设备
      */
+    @Operation(summary = "根据deviceId获取设备信息")
     @PostMapping("device/info/deviceId")
     public MyResp<DeviceRespDTO> getDeviceByDeviceId(@RequestBody DeviceSearchDTO deviceSearchDTO) {
         DeviceRespDTO deviceRespDTO = deviceService.getDeviceByDeviceId(deviceSearchDTO);

src/main/java/com/zjyr/beidouservice/controller/DeviceTaskController.java

@@ -8,6 +8,8 @@ import com.zjyr.beidouservice.pojo.dto.task.AlarmDeviceTaskListReqDTO;
 import com.zjyr.beidouservice.pojo.dto.task.AlarmTaskListReqDTO;
 import com.zjyr.beidouservice.pojo.dto.task.AlarmTaskReqDTO;
 import com.zjyr.beidouservice.service.AlarmTaskService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.validation.annotation.Validated;
@@ -21,6 +23,7 @@ import org.springframework.web.bind.annotation.RestController;
 @RequestMapping("/")
 @Validated
 @Slf4j
+@Tag(name = "告警任务接口")
 public class DeviceTaskController {
 
     @Resource
@@ -32,16 +35,19 @@ public class DeviceTaskController {
      * @param alarmTaskReqDTO alarmTaskReqDTO
      * @return MyResp
      */
+    @Operation(summary = "执行告警任务")
     @PostMapping("/alarm/task/exec")
-    public MyResp alarmTaskExec(@RequestBody AlarmTaskReqDTO alarmTaskReqDTO) {
+    public MyResp<String> alarmTaskExec(@RequestBody AlarmTaskReqDTO alarmTaskReqDTO) {
         return alarmTaskService.alarmTaskExec(alarmTaskReqDTO);
     }
 
+    @Operation(summary = "获取设备告警任务信息")
     @PostMapping("/alarm/task/list")
     public MyResp<AlarmTaskListRespDTO> alarmTaskList(@RequestBody AlarmTaskListReqDTO alarmTaskReqDTO) {
         return MyResp.success(alarmTaskService.alarmTaskList(alarmTaskReqDTO));
     }
 
+    @Operation(summary = "获取设备告警任务详情")
     @PostMapping("/alarm/device/task/list")
     public MyResp<AlarmDeviceTaskListRespDTO> alarmDeviceTaskList(@RequestBody AlarmDeviceTaskListReqDTO alarmDeviceTaskListReqDTO) {
         return MyResp.success(alarmTaskService.alarmDeviceTaskList(alarmDeviceTaskListReqDTO));

src/main/java/com/zjyr/beidouservice/controller/LocationController.java

@@ -3,10 +3,12 @@ package com.zjyr.beidouservice.controller;
 import com.zjyr.beidouservice.pojo.MyResp;
 import com.zjyr.beidouservice.pojo.dto.city.CityRespDTO;
 import com.zjyr.beidouservice.pojo.dto.city.CitySearchDTO;
-import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceResp;
+import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceSearchDTO;
 import com.zjyr.beidouservice.service.LocationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.validation.annotation.Validated;
@@ -15,32 +17,38 @@ import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+import java.util.List;
+
 @RestController
 @RequestMapping("/")
 @Validated
 @Slf4j
+@Tag(name = "位置接口")
 public class LocationController {
 
     @Resource
     LocationService locationService;
 
 
+    @Operation(summary = "获取省份信息")
     @PostMapping("only/provinces")
-    public MyResp<OnlyProvinceResp> getOnlyProvinces() {
+    public MyResp<List<OnlyProvinceRespDTO>> getOnlyProvinces() {
-        OnlyProvinceResp onlyProvinceResp = locationService.getOnlyProvinces();
+        List<OnlyProvinceRespDTO> onlyProvinceResp = locationService.getOnlyProvinces();
         return MyResp.success(onlyProvinceResp);
     }
 
+    @Operation(summary = "获取省份及对应地市信息")
     @PostMapping("provinces")
-    public MyResp<ProvinceRespDTO> getProvinces(@RequestBody ProvinceSearchDTO provinceSearchDTO) {
+    public MyResp<List<ProvinceRespDTO>> getProvinces(@RequestBody ProvinceSearchDTO provinceSearchDTO) {
-        ProvinceRespDTO provinceResp = locationService.getProvinces(provinceSearchDTO);
+        List<ProvinceRespDTO> provinceResp = locationService.getProvinces(provinceSearchDTO);
         return MyResp.success(provinceResp);
     }
 
 
+    @Operation(summary = "获取省份地市及区域信息")
     @PostMapping("citys")
-    public MyResp<CityRespDTO> getCity(@RequestBody CitySearchDTO citySearchDTO) {
+    public MyResp<List<CityRespDTO>> getCity(@RequestBody CitySearchDTO citySearchDTO) {
-        CityRespDTO cityResp = locationService.getCity(citySearchDTO);
+        List<CityRespDTO> cityResp = locationService.getCity(citySearchDTO);
         return MyResp.success(cityResp);
     }
 

src/main/java/com/zjyr/beidouservice/pojo/MyResp.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -9,10 +10,24 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "响应")
 public class MyResp<T> {
-
+    /**
+     * code
+     */
+    @Schema(title = "code", example = "0")
     private int    code = Resp.SUCCESS.getCede();
+
+    /**
+     * msg
+     */
+    @Schema(title = "msg", example = "成功")
     private String msg;
+
+    /**
+     * 响应数据
+     */
+    @Schema(title = "data", example = "")
     private T      data;
 
     public static MyResp build() {

src/main/java/com/zjyr/beidouservice/pojo/dto/AlarmDeviceTaskListRespDTO.java

@@ -1,8 +1,8 @@
 package com.zjyr.beidouservice.pojo.dto;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
-import com.zjyr.beidouservice.pojo.dataobject.AlarmDeviceTaskDO;
 import com.zjyr.beidouservice.pojo.vo.PageInfoVO;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -15,34 +15,63 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "任务详情信息响应体")
 public class AlarmDeviceTaskListRespDTO {
-
+    /**
+     * 任务详情信息
+     */
+    @Schema(title = "任务详情信息")
     private List<AlarmDeviceTaskDTO> deviceList;
 
+    /**
+     * 分页信息
+     */
+    @Schema(title = "分页信息")
     private PageInfoVO pageInfo;
 
     @Data
     public static class AlarmDeviceTaskDTO {
-
+        /**
+         * 任务id
+         */
+        @Schema(title = "任务id", example = "10", description = "任务id")
         private Long taskId;
 
+        /**
+         * 设备id
+         */
+        @Schema(title = "设备id", example = "123", description = "设备id")
         private Integer deviceId;
 
+        /**
+         * 终端名称
+         */
+        @Schema(title = "设备名称", example = "大运河002", description = "设备名称")
         private String deviceName;
 
+        /**
+         * 回示时间
+         */
+        @Schema(title = "回示时间", example = "2023-08-26 21:00:05", description = "回示时间")
         @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
         private Date reportTime;
 
+        /**
+         * 任务状态
+         */
+        @Schema(title = "任务状态", example = "0", description = "0:成功 1:错误 2:超时，相当于未响应 4:执行中")
         private Integer taskState;
 
         /**
          * 经度
          */
+        @Schema(title = "设备经度", example = "372.12", description = "经度")
         private Float latitude;
 
         /**
          * 纬度
          */
+        @Schema(title = "设备维度", example = "37.90", description = "纬度")
         private Float longitude;
     }
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/AlarmTaskListRespDTO.java

@@ -2,6 +2,7 @@ package com.zjyr.beidouservice.pojo.dto;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
 import com.zjyr.beidouservice.pojo.vo.PageInfoVO;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -14,29 +15,64 @@ import java.util.List;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "任务信息响应体")
 public class AlarmTaskListRespDTO {
-
+    /**
+     * 任务信息
+     */
+    @Schema(title = "任务信息")
     private List<AlarmTaskRespDTO> taskList;
 
+    /**
+     * 分页信息
+     */
+    @Schema(title = "分页信息")
     private PageInfoVO pageInfo;
 
     @Data
     @Builder
     public static class AlarmTaskRespDTO {
-
+        /**
+         * 任务id
+         */
+        @Schema(title = "任务id", example = "10")
         private Long id;
 
+        /**
+         * 任务编号
+         */
+        @Schema(title = "任务编号", example = "JL202308250020",description = "记录编号")
         private String taskIdStr;
 
+        /**
+         * 记录时间
+         */
+        @Schema(title = "记录时间", example = "2023-08-26 21:00:05",description = "记录时间")
         @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
         private Date recodeTime;
 
+        /**
+         * 执行设备数量
+         */
+        @Schema(title = "执行设备数量", example = "21", description = "该值还为大屏警报总数值")
         private Integer deviceNum;
 
+        /**
+         * 设备正常个数
+         */
+        @Schema(title = "设备正常个数", example = "2", description = "设备正常包括响应成功和响应失败")
         private Integer execNormalNum;
 
+        /**
+         * 设备异常个数
+         */
+        @Schema(title = "设备异常个数", example = "2", description = "设备正常为响应超时。正常+异常不一定等于总数量，还有执行中的任务")
         private Integer execAbnormalNum;
 
+        /**
+         * 回示率
+         */
+        @Schema(title = "回示率", example = "88.8", description = "设备正常个数/设备总数量")
         private Double respRate;
     }
 

src/main/java/com/zjyr/beidouservice/pojo/dto/DeviceReqDTO.java

@@ -1,6 +1,7 @@
 package com.zjyr.beidouservice.pojo.dto;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -10,24 +11,29 @@ import lombok.NoArgsConstructor;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "终端请求体")
 public class DeviceReqDTO {
     /**
      * 终端名称
      */
+    @Schema(title = "终端名称", example = "小河直街001号", description = "该值为null查询所有")
     private String deviceName;
 
     /**
      * 所属区县
      */
+    @Schema(title = "区县代码", example = "11", description = "该值为null查询所有区域")
     private Integer countyCode;
     /**
      * 所属地市
      */
+    @Schema(title = "地市代码", example = "20", description = "该值为null查询所有地市")
     private Integer cityCode;
 
     /**
      * 所属省份
      */
+    @Schema(title = "省份代码", example = "1", description = "该值为null查询所有省份")
     private Integer provinceCode;
 
 

src/main/java/com/zjyr/beidouservice/pojo/dto/DeviceRespDTO.java

@@ -3,6 +3,7 @@ package com.zjyr.beidouservice.pojo.dto;
 
 import com.zjyr.beidouservice.constenum.DeviceAlarmStatusEnum;
 import com.zjyr.beidouservice.pojo.dataobject.DeviceDO;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,50 +13,60 @@ import lombok.NoArgsConstructor;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(name = "设备请求返回体")
 public class DeviceRespDTO {
 
     /**
      * 设备id
      */
+    @Schema(title = "设备id", example = "123")
     private Integer deviceId;
 
     /**
      * 终端名称
      */
+    @Schema(title = "设备名称", example = "大运河002")
     private String deviceName;
 
     /**
      * 经度
      */
+    @Schema(title = "设备经度", example = "372.12")
     private Float latitude;
 
     /**
      * 纬度
      */
+    @Schema(title = "设备维度", example = "37.90")
     private Float longitude;
 
     /**
      * 所属区县
      */
+    @Schema(title = "区县代码", example = "90")
     private Integer countyCode;
     /**
      * 所属地市
      */
+    @Schema(title = "所属地市", example = "1")
     private Integer cityCode;
 
     /**
      * 所属省份
      */
+    @Schema(title = "所属省份", example = "33")
     private Integer provinceCode;
 
     /**
      * 安装地址
      */
+    @Schema(title = "安装地址", example = "余杭区五常街道")
     private String installSite;
 
     /**
      * 是否告警中
      */
+    @Schema(title = "是否告警中", example = "false", description = "false为非告警中，true为告警中")
     private Boolean isAlarming;
 
     public static DeviceRespDTO fromDO(DeviceDO deviceDO) {

src/main/java/com/zjyr/beidouservice/pojo/dto/DeviceSearchDTO.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -9,9 +10,11 @@ import lombok.NoArgsConstructor;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "设备查询请求体")
 public class DeviceSearchDTO {
     /**
      * 设备id
      */
+    @Schema(title = "设备ID", example = "1")
     private Integer deviceId;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/city/CityCountyDTO.java

@@ -1,19 +0,0 @@
-package com.zjyr.beidouservice.pojo.dto.city;
-
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-import java.util.List;
-
-
-@Data
-@NoArgsConstructor
-public class CityCountyDTO {
-    private Integer provinceCode;
-
-    private String cityName;
-
-    private Integer cityCode;
-
-    List<CountyContent> countyList;
-}

src/main/java/com/zjyr/beidouservice/pojo/dto/city/CityRespDTO.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo.dto.city;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
@@ -7,7 +8,30 @@ import java.util.List;
 
 @Data
 @NoArgsConstructor
+@Schema(name = "省份地市区域请求返回体")
 public class CityRespDTO {
 
-    List<CityCountyDTO> cityList;
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属省份编码", example = "33")
+    private Integer provinceCode;
+
+    /**
+     * 所属地市名称
+     */
+    @Schema(title = "所属地市名称", example = "杭州市")
+    private String cityName;
+
+    /**
+     * 所属地市编码
+     */
+    @Schema(title = "所属地市编码", example = "1")
+    private Integer cityCode;
+
+    /**
+     * 地市对应区域信息
+     */
+    @Schema(title = "所属地市对应区域信息")
+    List<CountyContent> countyList;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/city/CitySearchDTO.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo.dto.city;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,8 +10,17 @@ import java.io.Serializable;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(name = "省份地市请求体")
 public class CitySearchDTO implements Serializable {
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属省份编码", example = "33",description = "provinceCode为null,查询所有省份信息" )
     private Integer provinceCode;
 
+    /**
+     * 所属地市编码
+     */
+    @Schema(title = "所属地市编码", example = "33",description = "cityCode为null,查询所有地市信息" )
     private Integer cityCode;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/city/CountyContent.java

@@ -1,12 +1,22 @@
 package com.zjyr.beidouservice.pojo.dto.city;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
 @Data
 @NoArgsConstructor
+@Schema(name = "地市对应区域请求返回体")
 public class CountyContent {
+    /**
+     * 所属区域名称
+     */
+    @Schema(title = "所属区域名称", example = "余杭区")
     private String countyName;
 
+    /**
+     * 所属区域编码
+     */
+    @Schema(title = "所属区域编码", example = "1")
     private Integer countyCode;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/province/CityContentDTO.java

@@ -1,14 +1,24 @@
 package com.zjyr.beidouservice.pojo.dto.province;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
 
 @Data
 @NoArgsConstructor
+@Schema(name = "省份对应地市请求返回体")
 public class CityContentDTO {
+    /**
+     * 所属地市名称
+     */
+    @Schema(title = "所属地市名称", example = "杭州市")
     private String cityName;
 
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属地市编码", example = "1")
     private Integer cityCode;
 
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/province/OnlyProvinceContentDTO.java

@@ -1,12 +0,0 @@
-package com.zjyr.beidouservice.pojo.dto.province;
-
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-@Data
-@NoArgsConstructor
-public class OnlyProvinceContentDTO {
-    private String provinceName;
-
-    private Integer provinceCode;
-}

src/main/java/com/zjyr/beidouservice/pojo/dto/province/OnlyProvinceResp.java

@@ -1,12 +0,0 @@
-package com.zjyr.beidouservice.pojo.dto.province;
-
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-import java.util.List;
-
-@Data
-@NoArgsConstructor
-public class OnlyProvinceResp {
-    List<OnlyProvinceContentDTO> onlyProvinceList;
-}

src/main/java/com/zjyr/beidouservice/pojo/dto/province/OnlyProvinceRespDTO.java

@@ -0,0 +1,22 @@
+package com.zjyr.beidouservice.pojo.dto.province;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@Schema(name = "省份请求返回体")
+public class OnlyProvinceRespDTO {
+    /**
+     * 所属省份名称
+     */
+    @Schema(title = "所属省份名称", example = "浙江省")
+    private String provinceName;
+
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属省份编码", example = "33")
+    private Integer provinceCode;
+}

src/main/java/com/zjyr/beidouservice/pojo/dto/province/ProvinceContent.java

@@ -1,16 +0,0 @@
-package com.zjyr.beidouservice.pojo.dto.province;
-
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-import java.util.List;
-
-@Data
-@NoArgsConstructor
-public class ProvinceContent {
-    private String provinceName;
-
-    private Integer provinceCode;
-
-    private List<CityContentDTO> cityList;
-}

src/main/java/com/zjyr/beidouservice/pojo/dto/province/ProvinceRespDTO.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo.dto.province;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
@@ -7,6 +8,23 @@ import java.util.List;
 
 @Data
 @NoArgsConstructor
+@Schema(name = "省份地市请求返回体")
 public class ProvinceRespDTO {
-    List<ProvinceContent> provinceList;
+    /**
+     * 所属省份名称
+     */
+    @Schema(title = "所属省份名称", example = "浙江省")
+    private String provinceName;
+
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属省份编码", example = "33")
+    private Integer provinceCode;
+
+    /**
+     * 省份对应地市信息
+     */
+    @Schema(title = "所属省份对应地市信息")
+    private List<CityContentDTO> cityList;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/province/ProvinceSearchDTO.java

@@ -1,5 +1,6 @@
 package com.zjyr.beidouservice.pojo.dto.province;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@@ -9,7 +10,11 @@ import java.io.Serializable;
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(name = "省份请求体")
 public class ProvinceSearchDTO implements Serializable {
-
+    /**
+     * 所属省份编码
+     */
+    @Schema(title = "所属省份编码", example = "33",description = "provinceCode为null,查询所有省份信息" )
     private Integer provinceCode;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/task/AlarmDeviceTaskListReqDTO.java

@@ -1,15 +1,29 @@
 package com.zjyr.beidouservice.pojo.dto.task;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.util.List;
 
 @Data
+@Schema(title = "任务详情请求体")
 public class AlarmDeviceTaskListReqDTO {
 
+    /**
+     * 每页展示数量
+     */
+    @Schema(title = "每页展示数量", example = "10")
     private Integer pageSize;
 
+    /**
+     * 查询页数
+     */
+    @Schema(title = "查询页数", example = "1")
     private Integer pageNum;
 
+    /**
+     * 任务编号数组
+     */
+    @Schema(title = "任务编号", example = "[\"JL202308250020\"]", description = "任务编号可以携带多个。该值为null时查询所有任务信息")
     private List<String> taskIdStrList;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/task/AlarmTaskListReqDTO.java

@@ -1,15 +1,28 @@
 package com.zjyr.beidouservice.pojo.dto.task;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.util.List;
 
 @Data
+@Schema(title = "任务信息请求体")
 public class AlarmTaskListReqDTO {
-
+    /**
+     * 每页展示数量
+     */
+    @Schema(title = "每页展示数量", example = "10")
     private Integer pageSize;
 
+    /**
+     * 查询页数
+     */
+    @Schema(title = "查询页数", example = "1")
     private Integer pageNum;
 
+    /**
+     * 任务编号数组
+     */
+    @Schema(title = "任务编号", example = "[\"JL202308250020\"]", description = "任务编号可以携带多个。该值为null时查询所有任务信息")
     private List<String> taskIdStrList;
 }

src/main/java/com/zjyr/beidouservice/pojo/dto/task/AlarmTaskReqDTO.java

@@ -1,6 +1,7 @@
 package com.zjyr.beidouservice.pojo.dto.task;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
@@ -12,53 +13,64 @@ import java.util.Date;
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+@Schema(title = "任务执行请求体")
 public class AlarmTaskReqDTO {
     /**
      * 省份，默认浙江省 33.
      */
+    @Schema(title = "所属省份编码", example = "33", description = "默认浙江省")
     private String provinceCode;
     /**
      * 地市，默认杭州市 1.
      */
+    @Schema(title = "所属地市编码", example = "1",description = "默认杭州市，选择杭州市所有设备则该值不为null")
     private String cityCode;
     /**
      * 所属区域
      */
+    @Schema(title = "所属区域编码", example = "1",description = "多个区域用逗号分隔,如1,2,3，选择区域所有设备则该值不为null")
     private String countyCode;
 
     /**
      * 设备id.包含多个设备信息
      */
+    @Schema(title = "所属区域编码", example = "1,2,3",description = "多个设备Id用逗号分隔,如1,2,3，选择指定设备则该值不为null")
     private String deviceIds;
 
     /**
      * 警报类型 1:语言广播 2:警报发送 3:警报试鸣,默认警报发送2
      */
+    @Schema(title = "警报类型", example = "2",description = "1:语言广播 2:警报发送 3:警报试鸣,默认警报发送2")
     private Integer alarmType;
 
     /**
      * 警报种类 1:预先警报 2:空袭警报 3:灾情警 4:解除警报灾 5:解除警报
      */
+    @Schema(title = "警报种类", example = "2",description = "1:预先警报 2:空袭警报 3:灾情警 4:解除警报灾 5:解除警报")
     private Integer alarmKind;
 
     /**
      * 警报方式 1:人工 2:定时，默认人工
      */
+    @Schema(title = "警报方式", example = "1",description = "警报方式 1:人工 2:定时，默认人工")
     private Integer alarmMode;
 
     /**
      * 控制通道。1:无线 2:北斗 4:电话 7:all
      */
+    @Schema(title = "控制通道", example = "2",description = "1:无线 2:北斗 4:电话 7:all，默认北斗")
     private Integer controlChannel;
 
     /**
      * 发放时间
      */
-    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone="GMT+8")
+    @Schema(title = "发放时间", example = "2023-08-26 9:57:00")
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
     private Date sendTime;
 
     /**
      * 发放人
      */
+    @Schema(title = "发放人", example = "admin",description = "默认admin")
     private String sender;
 }

src/main/java/com/zjyr/beidouservice/pojo/vo/PageInfoVO.java

@@ -1,14 +1,27 @@
 package com.zjyr.beidouservice.pojo.vo;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 @Data
+@Schema(title = "分页信息响应体")
 public class PageInfoVO {
-
+    /**
+     * 总数
+     */
+    @Schema(title = "总数", example = "12")
     private Long total;
 
+    /**
+     * 每页展示数量
+     */
+    @Schema(title = "每页展示数量", example = "10")
     private Integer pageSize;
 
+    /**
+     * 查询页数
+     */
+    @Schema(title = "查询页数", example = "1")
     private Integer pageNum;
 
     public PageInfoVO(Long total, Integer pageSize, Integer pageNum) {

src/main/java/com/zjyr/beidouservice/service/AlarmTaskService.java

@@ -15,7 +15,7 @@ public interface AlarmTaskService {
      * @param alarmTaskReqDTO alarmTaskReqDTO
      * @return MyResp
      */
-    MyResp alarmTaskExec(AlarmTaskReqDTO alarmTaskReqDTO);
+    MyResp<String> alarmTaskExec(AlarmTaskReqDTO alarmTaskReqDTO);
 
 
     AlarmTaskListRespDTO alarmTaskList(AlarmTaskListReqDTO alarmTaskReqDTO);

src/main/java/com/zjyr/beidouservice/service/LocationService.java

@@ -2,16 +2,18 @@ package com.zjyr.beidouservice.service;
 
 import com.zjyr.beidouservice.pojo.dto.city.CityRespDTO;
 import com.zjyr.beidouservice.pojo.dto.city.CitySearchDTO;
-import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceResp;
+import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceSearchDTO;
 
+import java.util.List;
+
 public interface LocationService {
-    OnlyProvinceResp getOnlyProvinces();
+    List<OnlyProvinceRespDTO> getOnlyProvinces();
 
-    ProvinceRespDTO getProvinces(ProvinceSearchDTO provinceSearchDTO);
+    List<ProvinceRespDTO> getProvinces(ProvinceSearchDTO provinceSearchDTO);
 
-    CityRespDTO getCity(CitySearchDTO citySearchDTO);
+    List<CityRespDTO> getCity(CitySearchDTO citySearchDTO);
 
 
 }

src/main/java/com/zjyr/beidouservice/service/impl/AlarmTaskServiceImpl.java

@@ -99,7 +99,7 @@ public class AlarmTaskServiceImpl implements AlarmTaskService {
                 .approvalStatus(ApprovalStatusEnum.APPROVAL_SUCCESS.getCode()).build();
 
         //入库
-        Long generatedId = alarmTaskMapper.addAlarmTask(alarmTaskDO);
+        Long generatedId =  alarmTaskMapper.addAlarmTask(alarmTaskDO);
 
         List<AlarmDeviceTaskDO> alarmDeviceTaskDOS = getAlarmDeviceTaskDOS(alarmTaskReqDTO, deviceInfo, generatedId);
         alarmDeviceTaskMapper.addAlarmDevTaskInfoList(alarmDeviceTaskDOS);
@@ -118,7 +118,7 @@ public class AlarmTaskServiceImpl implements AlarmTaskService {
                 deviceInfo.getDeviceIds()
         );
 
-        return MyResp.build();
+        return MyResp.success("执行任务成功");
 
     }
 

src/main/java/com/zjyr/beidouservice/service/impl/LocationServiceImpl.java

@@ -6,14 +6,11 @@ import com.zjyr.beidouservice.mapper.LocProvinceMapper;
 import com.zjyr.beidouservice.pojo.dataobject.LocCityDO;
 import com.zjyr.beidouservice.pojo.dataobject.LocCountyDO;
 import com.zjyr.beidouservice.pojo.dataobject.LocProvinceDO;
-import com.zjyr.beidouservice.pojo.dto.city.CityCountyDTO;
 import com.zjyr.beidouservice.pojo.dto.city.CityRespDTO;
 import com.zjyr.beidouservice.pojo.dto.city.CitySearchDTO;
 import com.zjyr.beidouservice.pojo.dto.city.CountyContent;
 import com.zjyr.beidouservice.pojo.dto.province.CityContentDTO;
-import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceContentDTO;
+import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceRespDTO;
-import com.zjyr.beidouservice.pojo.dto.province.OnlyProvinceResp;
-import com.zjyr.beidouservice.pojo.dto.province.ProvinceContent;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceRespDTO;
 import com.zjyr.beidouservice.pojo.dto.province.ProvinceSearchDTO;
 import com.zjyr.beidouservice.service.LocationService;
@@ -37,46 +34,43 @@ public class LocationServiceImpl implements LocationService {
     LocCountyMapper locCountyMapper;
 
     @Override
-    public OnlyProvinceResp getOnlyProvinces() {
+    public List<OnlyProvinceRespDTO> getOnlyProvinces() {
-        OnlyProvinceResp onlyProvinceResp = new OnlyProvinceResp();
+        List<OnlyProvinceRespDTO> onlyProvinceList = new ArrayList<>();
-        List<OnlyProvinceContentDTO> onlyProvinceList = new ArrayList<>();
 
         //获取省份信息
         List<LocProvinceDO> provinceDOS = locProvinceMapper.selectAllProvince();
         if (provinceDOS.isEmpty()) {
             log.warn("不存在省份信息");
-            return new OnlyProvinceResp();
+            return new ArrayList<>();
         }
 
         provinceDOS.forEach(province -> {
-            OnlyProvinceContentDTO onlyProvinceContent = new OnlyProvinceContentDTO();
+            OnlyProvinceRespDTO onlyProvinceContent = new OnlyProvinceRespDTO();
             onlyProvinceContent.setProvinceName(province.getProvinceName());
             onlyProvinceContent.setProvinceCode(province.getProvinceCode());
             onlyProvinceList.add(onlyProvinceContent);
         });
 
-        onlyProvinceResp.setOnlyProvinceList(onlyProvinceList);
+        return onlyProvinceList;
-        return onlyProvinceResp;
     }
 
     @Override
-    public ProvinceRespDTO getProvinces(ProvinceSearchDTO provinceSearchDTO) {
+    public List<ProvinceRespDTO> getProvinces(ProvinceSearchDTO provinceSearchDTO) {
-        ProvinceRespDTO provinceResp = new ProvinceRespDTO();
+        List<ProvinceRespDTO> provinceRespqDTOS = new ArrayList<>();
-        List<ProvinceContent> provinceContents = new ArrayList<>();
 
         //获取省份信息
         Integer provinceCode = provinceSearchDTO.getProvinceCode();
         List<LocProvinceDO> provinceDOS = locProvinceMapper.selectProvince(provinceCode);
         if (provinceDOS.isEmpty()) {
             log.warn("不存在省份信息");
-            return new ProvinceRespDTO();
+            return new ArrayList<>();
         }
 
 
         provinceDOS.forEach(province -> {
-            ProvinceContent provinceContent = new ProvinceContent();
+            ProvinceRespDTO provinceRespDTO = new ProvinceRespDTO();
-            provinceContent.setProvinceName(province.getProvinceName());
+            provinceRespDTO.setProvinceName(province.getProvinceName());
-            provinceContent.setProvinceCode(province.getProvinceCode());
+            provinceRespDTO.setProvinceCode(province.getProvinceCode());
 
             //根据省份查询对应的地市信息
             List<CityContentDTO> cityContentDTOList = new ArrayList<>();
@@ -88,20 +82,18 @@ public class LocationServiceImpl implements LocationService {
                 cityContentDTOList.add(cityContent);
             });
 
-            provinceContent.setCityList(cityContentDTOList);
+            provinceRespDTO.setCityList(cityContentDTOList);
-            provinceContents.add(provinceContent);
+            provinceRespqDTOS.add(provinceRespDTO);
 
         });
 
-        provinceResp.setProvinceList(provinceContents);
+        return provinceRespqDTOS;
-        return provinceResp;
     }
 
 
     @Override
-    public CityRespDTO getCity(CitySearchDTO citySearchDTO) {
+    public List<CityRespDTO> getCity(CitySearchDTO citySearchDTO) {
-        CityRespDTO cityResp = new CityRespDTO();
+        List<CityRespDTO> cityContents = new ArrayList<>();
-        List<CityCountyDTO> cityContents = new ArrayList<>();
 
         //获取地市信息
         Integer provinceCode = citySearchDTO.getProvinceCode();
@@ -109,14 +101,14 @@ public class LocationServiceImpl implements LocationService {
         List<LocCityDO> cityDOS = locCityMapper.selectCity(provinceCode, cityCode);
         if (cityDOS.isEmpty()) {
             log.warn("不存在地市信息");
-            return new CityRespDTO();
+            return new ArrayList<>();
         }
 
         cityDOS.forEach(city -> {
-            CityCountyDTO cityContent = new CityCountyDTO();
+            CityRespDTO cityRespDTO = new CityRespDTO();
-            cityContent.setProvinceCode(city.getProvinceCode());
+            cityRespDTO.setProvinceCode(city.getProvinceCode());
-            cityContent.setCityName(city.getCityName());
+            cityRespDTO.setCityName(city.getCityName());
-            cityContent.setCityCode(city.getCityCode());
+            cityRespDTO.setCityCode(city.getCityCode());
 
             //根据地市查询对应的区信息
             List<CountyContent> countyContentList = new ArrayList<>();
@@ -128,13 +120,12 @@ public class LocationServiceImpl implements LocationService {
                 countyContentList.add(countyContent);
             });
 
-            cityContent.setCountyList(countyContentList);
+            cityRespDTO.setCountyList(countyContentList);
-            cityContents.add(cityContent);
+            cityContents.add(cityRespDTO);
 
         });
 
-        cityResp.setCityList(cityContents);
+        return cityContents;
-        return cityResp;
     }
 
 }

src/main/resources/mappers/AlarmTaskMapper.xml

@@ -19,7 +19,7 @@
         <!--@mbg.generated-->
         insert into alarm_task
         <trim prefix="(" suffix=")" suffixOverrides=",">
-            <if test="taskId != null and taskId != ''">task_id_str,</if>
+            <if test="taskIdStr != null and taskIdStr != ''">task_id_str,</if>
             <if test="alarmType != null">alarm_type,</if>
             <if test="alarmKind != null">alarm_kind,</if>
             <if test="alarmCounty != null and alarmCounty != ''">alarm_county,</if>
@@ -31,7 +31,7 @@
             <if test="approvalStatus != null ">approval_status,</if>
         </trim>
         <trim prefix="values (" suffix=")" suffixOverrides=",">
-            <if test="taskId != null and taskId != ''">#{taskId},</if>
+            <if test="taskIdStr != null and taskIdStr != ''">#{taskIdStr},</if>
             <if test="alarmType != null">#{alarmType},</if>
             <if test="alarmKind != null">#{alarmKind},</if>
             <if test="alarmCounty != null and alarmCounty != ''">#{alarmCounty},</if>