feat: 升级swagger v3 #2883

TencentBlueKing · Feb 7, 2025 · 0b9e324 · 0b9e324
1 parent 42f7248
commit 0b9e324
Show file tree

Hide file tree

Showing 485 changed files with 4,527 additions and 4,513 deletions.
diff --git a/src/backend/README.md b/src/backend/README.md
@@ -30,7 +30,7 @@
 
 ### swagger地址
 
-${base-path}/v2/api-docs
+${base-path}/v3/api-docs
 
 配合chrome浏览器插件`Swagger UI Console`使用
 

diff --git a/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/api/ScanClient.kt b/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/api/ScanClient.kt
@@ -34,7 +34,7 @@ import com.tencent.bkrepo.analyst.pojo.request.ReportResultRequest
 import com.tencent.bkrepo.analyst.pojo.request.ScanRequest
 import com.tencent.bkrepo.common.api.constant.SCANNER_SERVICE_NAME
 import com.tencent.bkrepo.common.api.pojo.Response
-import io.swagger.annotations.ApiParam
+import io.swagger.v3.oas.annotations.Parameter
 import org.springframework.cloud.openfeign.FeignClient
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
@@ -95,7 +95,7 @@ interface ScanClient {
      */
     @PostMapping("/licenseIds")
     fun licenseInfoByIds(
-        @ApiParam(value = "许可证唯一标识集合")
+        @Parameter(name = "许可证唯一标识集合")
         @RequestBody licenseIds: List<String>
     ): Response<Map<String, SpdxLicenseInfo>>
 

diff --git a/...analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ArtifactScanReport.kt b/...analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ArtifactScanReport.kt
@@ -27,11 +27,11 @@
 
 package com.tencent.bkrepo.analyst.pojo
 
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
-@ApiModel("扫描报告")
+
+@Schema(title = "扫描报告")
 data class ArtifactScanReport(
-    @ApiModelProperty("扫描报告")
+    @get:Schema(title = "扫描报告")
     private val report: String
 )
diff --git a/...analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ArtifactScanStatus.kt b/...analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ArtifactScanStatus.kt
@@ -27,15 +27,15 @@
 
 package com.tencent.bkrepo.analyst.pojo
 
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
-@ApiModel("文件扫描状态")
+
+@Schema(title = "文件扫描状态")
 data class ArtifactScanStatus(
-    @ApiModelProperty("文件sha256")
+    @get:Schema(title = "文件sha256")
     val sha256: String,
-    @ApiModelProperty("文件路径")
+    @get:Schema(title = "文件路径")
     val fullPath: String,
-    @ApiModelProperty("文件扫描状态")
+    @get:Schema(title = "文件扫描状态")
     val status: String
 )
diff --git a/...lyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/AutoScanConfiguration.kt b/...lyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/AutoScanConfiguration.kt
@@ -27,13 +27,13 @@
 
 package com.tencent.bkrepo.analyst.pojo
 
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
-@ApiModel("自动扫描配置")
+
+@Schema(title = "自动扫描配置")
 data class AutoScanConfiguration(
-    @ApiModelProperty("自动扫描的仓库")
+    @get:Schema(title = "自动扫描的仓库")
     val autoScanRepoNames: List<String> = emptyList(),
-    @ApiModelProperty("自动扫描制品匹配规则")
+    @get:Schema(title = "自动扫描制品匹配规则")
     val autoScanMatchRule: String? = null
 )
diff --git a/...t/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ProjectScanConfiguration.kt b/...t/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ProjectScanConfiguration.kt
@@ -28,30 +28,30 @@
 package com.tencent.bkrepo.analyst.pojo
 
 import com.fasterxml.jackson.annotation.JsonInclude
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
+
 
 @JsonInclude(JsonInclude.Include.NON_NULL)
-@ApiModel("项目扫描配置")
+@Schema(title = "项目扫描配置")
 data class ProjectScanConfiguration(
-    @ApiModelProperty("项目ID")
+    @get:Schema(title = "项目ID")
     val projectId: String,
-    @ApiModelProperty("项目优先级，值越小优先级越低")
+    @get:Schema(title = "项目优先级，值越小优先级越低")
     val priority: Int? = null,
-    @ApiModelProperty("项目限制的扫描任务数量")
+    @get:Schema(title = "项目限制的扫描任务数量")
     val scanTaskCountLimit: Int? = null,
-    @ApiModelProperty("项目扫描子任务数量限制")
+    @get:Schema(title = "项目扫描子任务数量限制")
     val subScanTaskCountLimit: Int? = null,
-    @ApiModelProperty("自动扫描配置")
+    @get:Schema(title = "自动扫描配置")
     val autoScanConfiguration: Map<String, AutoScanConfiguration>? = null,
-    @ApiModelProperty("子任务分发器")
+    @get:Schema(title = "子任务分发器")
     val dispatcherConfiguration: List<DispatcherConfiguration>? = null
 )
 
-@ApiModel("分发器配置")
+@Schema(title = "分发器配置")
 data class DispatcherConfiguration(
-    @ApiModelProperty("使用的分发器")
+    @get:Schema(title = "使用的分发器")
     val dispatcher: String,
-    @ApiModelProperty("扫描器")
+    @get:Schema(title = "扫描器")
     val scanner: String
 )
diff --git a/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ScanPlan.kt b/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ScanPlan.kt
@@ -29,42 +29,42 @@ package com.tencent.bkrepo.analyst.pojo
 
 import com.fasterxml.jackson.annotation.JsonInclude
 import com.tencent.bkrepo.common.query.model.Rule
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
+
 
 @JsonInclude(JsonInclude.Include.NON_NULL)
-@ApiModel("扫描方案")
+@Schema(title = "扫描方案")
 data class ScanPlan(
-    @ApiModelProperty("方案ID")
+    @get:Schema(title = "方案ID")
     var id: String? = null,
-    @ApiModelProperty("项目ID")
+    @get:Schema(title = "项目ID")
     var projectId: String? = null,
-    @ApiModelProperty("方案名称")
+    @get:Schema(title = "方案名称")
     var name: String? = null,
-    @ApiModelProperty("方案类型")
+    @get:Schema(title = "方案类型")
     var type: String? = null,
-    @ApiModelProperty("扫描类型")
+    @get:Schema(title = "扫描类型")
     var scanTypes: List<String>? = null,
-    @ApiModelProperty("使用的扫描器")
+    @get:Schema(title = "使用的扫描器")
     var scanner: String? = null,
-    @ApiModelProperty("方案描述")
+    @get:Schema(title = "方案描述")
     var description: String? = null,
-    @ApiModelProperty("是否有新制品上传时自动扫描")
+    @get:Schema(title = "是否有新制品上传时自动扫描")
     var scanOnNewArtifact: Boolean? = null,
-    @ApiModelProperty("自动扫描仓库")
+    @get:Schema(title = "自动扫描仓库")
     var repoNames: List<String>? = null,
-    @ApiModelProperty("自动扫描规则")
+    @get:Schema(title = "自动扫描规则")
     var rule: Rule? = null,
-    @ApiModelProperty("质量规则")
+    @get:Schema(title = "质量规则")
     var scanQuality: Map<String, Any>? = null,
-    @ApiModelProperty("创建者")
+    @get:Schema(title = "创建者")
     var createdBy: String? = null,
-    @ApiModelProperty("创建时间")
+    @get:Schema(title = "创建时间")
     var createdDate: String? = null,
-    @ApiModelProperty("修改者")
+    @get:Schema(title = "修改者")
     var lastModifiedBy: String? = null,
-    @ApiModelProperty("修改时间")
+    @get:Schema(title = "修改时间")
     var lastModifiedDate: String? = null,
-    @ApiModelProperty("是否只读")
+    @get:Schema(title = "是否只读")
     var readOnly: Boolean? = null
 )
diff --git a/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ScanTask.kt b/src/backend/analyst/api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/ScanTask.kt
@@ -28,58 +28,58 @@
 package com.tencent.bkrepo.analyst.pojo
 
 import com.tencent.bkrepo.common.query.model.Rule
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
-@ApiModel("扫描任务信息")
+
+@Schema(title = "扫描任务信息")
 data class ScanTask(
-    @ApiModelProperty("扫描任务名")
+    @get:Schema(title = "扫描任务名")
     val name: String? = null,
-    @ApiModelProperty("任务id")
+    @get:Schema(title = "任务id")
     val taskId: String,
-    @ApiModelProperty("项目id，只扫描单个项目时有值")
+    @get:Schema(title = "项目id，只扫描单个项目时有值")
     val projectId: String?,
-    @ApiModelProperty("项目id")
+    @get:Schema(title = "项目id")
     val projectIds: Set<String>,
-    @ApiModelProperty("触发者")
+    @get:Schema(title = "触发者")
     val createdBy: String,
-    @ApiModelProperty("最后修改时间")
+    @get:Schema(title = "最后修改时间")
     val lastModifiedDateTime: String,
-    @ApiModelProperty("任务触发时间")
+    @get:Schema(title = "任务触发时间")
     val triggerDateTime: String,
-    @ApiModelProperty("任务开始执行时间")
+    @get:Schema(title = "任务开始执行时间")
     val startDateTime: String?,
-    @ApiModelProperty("任务执行结束时间")
+    @get:Schema(title = "任务执行结束时间")
     val finishedDateTime: String?,
-    @ApiModelProperty("触发方式")
+    @get:Schema(title = "触发方式")
     val triggerType: String,
-    @ApiModelProperty("任务状态")
+    @get:Schema(title = "任务状态")
     val status: String,
-    @ApiModelProperty("扫描方案")
+    @get:Schema(title = "扫描方案")
     val scanPlan: ScanPlan?,
-    @ApiModelProperty("扫描文件匹配规则")
+    @get:Schema(title = "扫描文件匹配规则")
     val rule: Rule?,
-    @ApiModelProperty("计划扫描文件总数")
+    @get:Schema(title = "计划扫描文件总数")
     val total: Long,
-    @ApiModelProperty("扫描中的文件总数")
+    @get:Schema(title = "扫描中的文件总数")
     val scanning: Long,
-    @ApiModelProperty("扫描失败的文件总数")
+    @get:Schema(title = "扫描失败的文件总数")
     val failed: Long,
-    @ApiModelProperty("已扫描文件总数")
+    @get:Schema(title = "已扫描文件总数")
     val scanned: Long,
-    @ApiModelProperty("通过质量规则的文件总数")
+    @get:Schema(title = "通过质量规则的文件总数")
     val passed: Long,
-    @ApiModelProperty("使用的扫描器")
+    @get:Schema(title = "使用的扫描器")
     val scanner: String,
-    @ApiModelProperty("扫描器类型")
+    @get:Schema(title = "扫描器类型")
     val scannerType: String,
-    @ApiModelProperty("扫描器版本")
+    @get:Schema(title = "扫描器版本")
     val scannerVersion: String,
-    @ApiModelProperty("扫描结果统计数据")
+    @get:Schema(title = "扫描结果统计数据")
     val scanResultOverview: Map<String, Long>?,
-    @ApiModelProperty("是否强制扫描")
+    @get:Schema(title = "是否强制扫描")
     val force: Boolean = false,
-    @ApiModelProperty("扫描任务元数据")
+    @get:Schema(title = "扫描任务元数据")
     val metadata: List<TaskMetadata>
 ) {
     fun isGlobal() = metadata.any { it.key == TaskMetadata.TASK_METADATA_GLOBAL && it.value == "true" }

diff --git a/...alyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/execution/DockerExecutionCluster.kt b/...alyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/execution/DockerExecutionCluster.kt
@@ -1,19 +1,19 @@
 package com.tencent.bkrepo.analyst.pojo.execution
 
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
 @Suppress("LongParameterList", "MagicNumber")
 data class DockerExecutionCluster(
     override val name: String,
-    @ApiModelProperty("docker host")
+    @get:Schema(title = "docker host")
     val host: String = "unix://var/run/docker.sock",
-    @ApiModelProperty("docker api version")
+    @get:Schema(title = "docker api version")
     val version: String = "1.23",
-    @ApiModelProperty("docker api connect timeout")
+    @get:Schema(title = "docker api connect timeout")
     val connectTimeout: Int = 5000,
-    @ApiModelProperty("docker api read timeout")
+    @get:Schema(title = "docker api read timeout")
     val readTimeout: Int = 0,
-    @ApiModelProperty("最大可同时执行的任务数量")
+    @get:Schema(title = "最大可同时执行的任务数量")
     val maxTaskCount: Int = 1
 ) : ExecutionCluster(name, type) {
     companion object {

diff --git a/...api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/execution/ExecutionCluster.kt b/...api-analyst/src/main/kotlin/com/tencent/bkrepo/analyst/pojo/execution/ExecutionCluster.kt
@@ -3,21 +3,21 @@ package com.tencent.bkrepo.analyst.pojo.execution
 import com.fasterxml.jackson.annotation.JsonSubTypes
 import com.fasterxml.jackson.annotation.JsonSubTypes.Type
 import com.fasterxml.jackson.annotation.JsonTypeInfo
-import io.swagger.annotations.ApiModel
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
 
-@ApiModel("任务执行集群配置")
+
+@Schema(title = "任务执行集群配置")
 @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "type")
 @JsonSubTypes(
     Type(value = KubernetesJobExecutionCluster::class, name = KubernetesJobExecutionCluster.type),
     Type(value = KubernetesDeploymentExecutionCluster::class, name = KubernetesDeploymentExecutionCluster.type),
     Type(value = DockerExecutionCluster::class, name = DockerExecutionCluster.type),
 )
 open class ExecutionCluster(
-    @ApiModelProperty("执行集群名")
+    @get:Schema(title = "执行集群名")
     open val name: String,
-    @ApiModelProperty("类型")
+    @get:Schema(title = "类型")
     val type: String,
-    @ApiModelProperty("描述")
+    @get:Schema(title = "描述")
     val description: String = "",
 )
diff --git a/.../kotlin/com/tencent/bkrepo/analyst/pojo/execution/KubernetesDeploymentExecutionCluster.kt b/.../kotlin/com/tencent/bkrepo/analyst/pojo/execution/KubernetesDeploymentExecutionCluster.kt
@@ -1,20 +1,21 @@
 package com.tencent.bkrepo.analyst.pojo.execution
 
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
+
 
 data class KubernetesDeploymentExecutionCluster(
     override val name: String,
-    @ApiModelProperty("使用的扫描器")
+    @get:Schema(title = "使用的扫描器")
     val scanner: String,
-    @ApiModelProperty("k8s配置")
+    @get:Schema(title = "k8s配置")
     val kubernetesProperties: KubernetesExecutionClusterProperties,
-    @ApiModelProperty("最大副本数")
+    @get:Schema(title = "最大副本数")
     val maxReplicas: Int = 1,
-    @ApiModelProperty("最小副本数")
+    @get:Schema(title = "最小副本数")
     val minReplicas: Int = 1,
-    @ApiModelProperty("目标副本数与当前副本数之差绝对值超过这个配置时将触发扩缩容")
+    @get:Schema(title = "目标副本数与当前副本数之差绝对值超过这个配置时将触发扩缩容")
     val scaleThreshold: Int = 1,
-    @ApiModelProperty("扫描器重试拉取任务次数，-1表示一直拉取直到拉取任务成功")
+    @get:Schema(title = "扫描器重试拉取任务次数，-1表示一直拉取直到拉取任务成功")
     val pullRetry: Int = 3,
 ) : ExecutionCluster(name, type) {
     companion object {

diff --git a/.../kotlin/com/tencent/bkrepo/analyst/pojo/execution/KubernetesExecutionClusterProperties.kt b/.../kotlin/com/tencent/bkrepo/analyst/pojo/execution/KubernetesExecutionClusterProperties.kt
@@ -1,27 +1,28 @@
 package com.tencent.bkrepo.analyst.pojo.execution
 
-import io.swagger.annotations.ApiModelProperty
+import io.swagger.v3.oas.annotations.media.Schema
+
 
 data class KubernetesExecutionClusterProperties(
-    @ApiModelProperty("命名空间")
+    @get:Schema(title = "命名空间")
     val namespace: String = "default",
-    @ApiModelProperty("k8s api server url")
+    @get:Schema(title = "k8s api server url")
     val apiServer: String? = null,
-    @ApiModelProperty("certificateAuthorityData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
+    @get:Schema(title = "certificateAuthorityData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
     val certificateAuthorityData: String? = null,
     // token认证
-    @ApiModelProperty("用于访问apiServer时进行认证，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
+    @get:Schema(title = "用于访问apiServer时进行认证，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
     val token: String? = null,
     // client cert认证
-    @ApiModelProperty("clientCertificateData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
+    @get:Schema(title = "clientCertificateData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
     val clientCertificateData: String? = null,
-    @ApiModelProperty("clientKeyData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
+    @get:Schema(title = "clientKeyData，未配置时取当前环境的~/.kube/config，或者当前部署的service account")
     val clientKeyData: String? = null,
-    @ApiModelProperty("集群允许的单容器最大内存使用")
+    @get:Schema(title = "集群允许的单容器最大内存使用")
     val limitMem: Long = 32 * GB,
-    @ApiModelProperty("集群允许单容器使用的最大ephemeralStorage")
+    @get:Schema(title = "集群允许单容器使用的最大ephemeralStorage")
     val limitStorage: Long = 128 * GB,
-    @ApiModelProperty("集群允许单容器使用的最大cpu")
+    @get:Schema(title = "集群允许单容器使用的最大cpu")
     val limitCpu: Double = 16.0
 ) {
     companion object {