feat: api文档更新 TencentBlueKing#11409

yongyiduan · Jan 15, 2025 · ba464f0 · ba464f0
1 parent 34f1e7e
commit ba464f0
Show file tree

Hide file tree

Showing 6 changed files with 46 additions and 25 deletions.
diff --git a/...in/com/tencent/devops/openapi/api/apigw/v3/environment/ApigwEnvironmentAgentResourceV3.kt b/...in/com/tencent/devops/openapi/api/apigw/v3/environment/ApigwEnvironmentAgentResourceV3.kt
@@ -71,7 +71,7 @@ interface ApigwEnvironmentAgentResourceV3 {
         projectId: String
     ): Result<List<NodeBaseInfo>>
 
-    @Operation(summary = "获取指定构建机状态", tags = ["v3_user_node_status", "v3_app_node_status"])
+    @Operation(summary = "获取指定第三方构建机状态", tags = ["v3_user_node_status", "v3_app_node_status"])
     @Path("/thirdPartAgent/nodes/status")
     @GET
     fun getNodeStatus(

diff --git a/.../kotlin/com/tencent/devops/openapi/api/apigw/v3/environment/ApigwEnvironmentResourceV3.kt b/.../kotlin/com/tencent/devops/openapi/api/apigw/v3/environment/ApigwEnvironmentResourceV3.kt
@@ -39,9 +39,9 @@ import com.tencent.devops.environment.pojo.NodeBaseInfo
 import com.tencent.devops.environment.pojo.NodeWithPermission
 import com.tencent.devops.environment.pojo.SharedProjectInfoWrap
 import com.tencent.devops.environment.pojo.thirdpartyagent.AgentPipelineRef
-import io.swagger.v3.oas.annotations.tags.Tag
 import io.swagger.v3.oas.annotations.Operation
 import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.tags.Tag
 import javax.ws.rs.Consumes
 import javax.ws.rs.DELETE
 import javax.ws.rs.GET
@@ -60,10 +60,13 @@ import javax.ws.rs.core.MediaType
 @Suppress("ALL")
 interface ApigwEnvironmentResourceV3 {
 
-    @Operation(summary = "获取用户有权限使用的服务器列表", tags = ["v3_user_env_list_usable_nodes", "v3_app_env_list_usable_nodes"])
+    @Operation(
+        summary = "获取用户有权限使用的CMDB服务器列表",
+        tags = ["v3_user_env_list_usable_nodes", "v3_app_env_list_usable_nodes"]
+    )
     @GET
     @Path("/projects/{projectId}/nodes/listUsableServerNodes")
-    fun listUsableServerNodes(
+    fun listUsableServerCMDBNodes(
         @Parameter(description = "appCode", required = true, example = AUTH_HEADER_DEVOPS_APP_CODE_DEFAULT_VALUE)
         @HeaderParam(AUTH_HEADER_DEVOPS_APP_CODE)
         appCode: String?,
@@ -185,7 +188,10 @@ interface ApigwEnvironmentResourceV3 {
         nodeHashIds: List<String>
     ): Result<Boolean>
 
-    @Operation(summary = "获取用户有权限使用的环境列表", tags = ["v3_app_env_list_usable_envs", "v3_user_env_list_usable_envs"])
+    @Operation(
+        summary = "获取用户有权限使用的CMDB环境列表",
+        tags = ["v3_app_env_list_usable_envs", "v3_user_env_list_usable_envs"]
+    )
     @GET
     @Path("/projects/{projectId}/envs/listUsableServerEnvs")
     fun listUsableServerEnvs(
@@ -204,7 +210,7 @@ interface ApigwEnvironmentResourceV3 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据环境名称获取环境信息(不校验权限)",
+        summary = "根据环境名称获取CMDB环境信息(不校验权限)",
         tags = ["v3_user_env_list_env_by_env_names", "v3_app_env_list_env_by_env_names"]
     )
     @POST
@@ -227,7 +233,7 @@ interface ApigwEnvironmentResourceV3 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据hashId(多个)获取环境信息(不校验权限)",
+        summary = "根据hashId(多个)获取CMDB环境信息(不校验权限)",
         tags = ["v3_app_env_list_by_env_hashIds", "v3_user_env_list_by_env_hashIds"]
     )
     @POST
@@ -250,7 +256,7 @@ interface ApigwEnvironmentResourceV3 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据hashId获取项目节点列表(不校验权限)",
+        summary = "根据hashId获取项目CMDB节点列表(不校验权限)",
         tags = ["v3_user_env_node_list_byNodeHashIds", "v3_app_env_node_list_byNodeHashIds"]
     )
     @POST
@@ -273,7 +279,7 @@ interface ApigwEnvironmentResourceV3 {
     ): Result<List<NodeBaseInfo>>
 
     @Operation(
-        summary = "根据环境的hashId获取指定项目指定环境下节点列表(不校验权限)",
+        summary = "根据环境的hashId获取指定项目指定CMDB环境下节点列表(不校验权限)",
         tags = ["v3_user_env_node_list_byEnvHashIds", "v3_app_env_node_list_byEnvHashIds"]
     )
     @POST
@@ -295,7 +301,10 @@ interface ApigwEnvironmentResourceV3 {
         envHashIds: List<String>
     ): Result<Map<String, List<NodeBaseInfo>>>
 
-    @Operation(summary = "获取构建节点信息（扩展接口）", tags = ["v3_user_env_node_list_ext", "v3_app_env_node_list_ext"])
+    @Operation(
+        summary = "获取第三方构建节点信息（扩展接口）",
+        tags = ["v3_user_env_node_list_ext", "v3_app_env_node_list_ext"]
+    )
     @GET
     @Path("/projects/{projectId}/nodes/extListNodes")
     fun extListNodes(
@@ -314,7 +323,7 @@ interface ApigwEnvironmentResourceV3 {
     ): Result<List<NodeWithPermission>>
 
     @Operation(
-        summary = "获取构建节点信息（扩展接口）",
+        summary = "获取第三方构建节点被流水线引用数据",
         tags = ["v3_user_env_node_list_pipeline_ref", "v3_app_env_node_list_pipeline_ref"]
     )
     @GET

diff --git a/...in/com/tencent/devops/openapi/api/apigw/v4/environment/ApigwEnvironmentAgentResourceV4.kt b/...in/com/tencent/devops/openapi/api/apigw/v4/environment/ApigwEnvironmentAgentResourceV4.kt
@@ -78,7 +78,7 @@ interface ApigwEnvironmentAgentResourceV4 {
         projectId: String
     ): Result<List<NodeBaseInfo>>
 
-    @Operation(summary = "获取指定构建机状态", tags = ["v4_user_node_status", "v4_app_node_status"])
+    @Operation(summary = "获取指定第三方构建机状态", tags = ["v4_user_node_status", "v4_app_node_status"])
     @Path("/third_part_agent_node_status")
     @GET
     fun getNodeStatus(

diff --git a/.../kotlin/com/tencent/devops/openapi/api/apigw/v4/environment/ApigwEnvironmentResourceV4.kt b/.../kotlin/com/tencent/devops/openapi/api/apigw/v4/environment/ApigwEnvironmentResourceV4.kt
@@ -39,9 +39,9 @@ import com.tencent.devops.environment.pojo.NodeBaseInfo
 import com.tencent.devops.environment.pojo.NodeWithPermission
 import com.tencent.devops.environment.pojo.SharedProjectInfoWrap
 import com.tencent.devops.environment.pojo.thirdpartyagent.AgentPipelineRef
-import io.swagger.v3.oas.annotations.tags.Tag
 import io.swagger.v3.oas.annotations.Operation
 import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.tags.Tag
 import javax.ws.rs.Consumes
 import javax.ws.rs.DELETE
 import javax.ws.rs.GET
@@ -60,10 +60,13 @@ import javax.ws.rs.core.MediaType
 @Suppress("ALL")
 interface ApigwEnvironmentResourceV4 {
 
-    @Operation(summary = "获取用户有权限使用的服务器列表", tags = ["v4_user_env_list_usable_nodes", "v4_app_env_list_usable_nodes"])
+    @Operation(
+        summary = "获取用户有权限使用的CMDB服务器列表",
+        tags = ["v4_user_env_list_usable_nodes", "v4_app_env_list_usable_nodes"]
+    )
     @GET
     @Path("/usable_server_nodes")
-    fun listUsableServerNodes(
+    fun listUsableServerCMDBNodes(
         @Parameter(description = "appCode", required = true, example = AUTH_HEADER_DEVOPS_APP_CODE_DEFAULT_VALUE)
         @HeaderParam(AUTH_HEADER_DEVOPS_APP_CODE)
         appCode: String?,
@@ -185,7 +188,10 @@ interface ApigwEnvironmentResourceV4 {
         nodeHashIds: List<String>
     ): Result<Boolean>
 
-    @Operation(summary = "获取用户有权限使用的环境列表", tags = ["v4_app_env_list_usable_envs", "v4_user_env_list_usable_envs"])
+    @Operation(
+        summary = "获取用户有权限使用的CMDB环境列表",
+        tags = ["v4_app_env_list_usable_envs", "v4_user_env_list_usable_envs"]
+    )
     @GET
     @Path("/usable_server_envs")
     fun listUsableServerEnvs(
@@ -204,7 +210,7 @@ interface ApigwEnvironmentResourceV4 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据环境名称获取环境信息(不校验权限)",
+        summary = "根据环境名称获取环境CMDB信息(不校验权限)",
         tags = ["v4_user_env_list_env_by_env_names", "v4_app_env_list_env_by_env_names"]
     )
     @POST
@@ -227,7 +233,7 @@ interface ApigwEnvironmentResourceV4 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据hashId(多个)获取环境信息(不校验权限)",
+        summary = "根据hashId(多个)获取CMDB环境信息(不校验权限)",
         tags = ["v4_app_env_list_by_env_hashIds", "v4_user_env_list_by_env_hashIds"]
     )
     @POST
@@ -250,7 +256,7 @@ interface ApigwEnvironmentResourceV4 {
     ): Result<List<EnvWithPermission>>
 
     @Operation(
-        summary = "根据hashId获取项目节点列表(不校验权限)",
+        summary = "根据hashId获取项目CMDB节点列表(不校验权限)",
         tags = ["v4_user_env_node_list_byNodeHashIds", "v4_app_env_node_list_byNodeHashIds"]
     )
     @POST
@@ -273,7 +279,7 @@ interface ApigwEnvironmentResourceV4 {
     ): Result<List<NodeBaseInfo>>
 
     @Operation(
-        summary = "根据环境的hashId获取指定项目指定环境下节点列表(不校验权限)",
+        summary = "根据环境的hashId获取指定项目指定CMDB环境下节点列表(不校验权限)",
         tags = ["v4_user_env_node_list_byEnvHashIds", "v4_app_env_node_list_byEnvHashIds"]
     )
     @POST
@@ -295,7 +301,10 @@ interface ApigwEnvironmentResourceV4 {
         envHashIds: List<String>
     ): Result<Map<String, List<NodeBaseInfo>>>
 
-    @Operation(summary = "获取构建节点信息（扩展接口）", tags = ["v4_user_env_node_list_ext", "v4_app_env_node_list_ext"])
+    @Operation(
+        summary = "获取第三方构建节点信息（扩展接口）",
+        tags = ["v4_user_env_node_list_ext", "v4_app_env_node_list_ext"]
+    )
     @GET
     @Path("/ext_nodes")
     fun extListNodes(
@@ -314,7 +323,7 @@ interface ApigwEnvironmentResourceV4 {
     ): Result<List<NodeWithPermission>>
 
     @Operation(
-        summary = "获取构建节点信息（扩展接口）",
+        summary = "获取第三方构建节点被流水线引用数据",
         tags = ["v4_user_env_node_list_pipeline_ref", "v4_app_env_node_list_pipeline_ref"]
     )
     @GET
@@ -360,7 +369,10 @@ interface ApigwEnvironmentResourceV4 {
         sharedProjects: SharedProjectInfoWrap
     ): Result<Boolean>
 
-    @Operation(summary = "指定构建环境获取所有节点信息", tags = ["v4_user_third_party_env2nodes", "v4_app_third_party_env2nodes"])
+    @Operation(
+        summary = "指定第三方构建环境获取所有第三方构建机节点信息",
+        tags = ["v4_user_third_party_env2nodes", "v4_app_third_party_env2nodes"]
+    )
     @GET
     @Path("/third_party_env2nodes")
     fun thirdPartyEnv2Nodes(

diff --git a/...m/tencent/devops/openapi/resources/apigw/v3/environment/ApigwEnvironmentResourceV3Impl.kt b/...m/tencent/devops/openapi/resources/apigw/v3/environment/ApigwEnvironmentResourceV3Impl.kt
@@ -51,7 +51,7 @@ class ApigwEnvironmentResourceV3Impl @Autowired constructor(
 ) : ApigwEnvironmentResourceV3 {
 
     @BkTimed(extraTags = ["operate", "getNode"])
-    override fun listUsableServerNodes(
+    override fun listUsableServerCMDBNodes(
         appCode: String?,
         apigwType: String?,
         userId: String,

diff --git a/...m/tencent/devops/openapi/resources/apigw/v4/environment/ApigwEnvironmentResourceV4Impl.kt b/...m/tencent/devops/openapi/resources/apigw/v4/environment/ApigwEnvironmentResourceV4Impl.kt
@@ -48,7 +48,7 @@ import org.springframework.beans.factory.annotation.Autowired
 class ApigwEnvironmentResourceV4Impl @Autowired constructor(
     private val client: Client
 ) : ApigwEnvironmentResourceV4 {
-    override fun listUsableServerNodes(
+    override fun listUsableServerCMDBNodes(
         appCode: String?,
         apigwType: String?,
         userId: String,