diff --git a/apollo-openapi.yaml b/apollo-openapi.yaml
index f8343fd5..c99fdff2 100644
--- a/apollo-openapi.yaml
+++ b/apollo-openapi.yaml
@@ -2,34 +2,22 @@ openapi: 3.0.1
 info:
   title: Apollo OpenAPI
   description: |
-    Apollo配置中心OpenAPI接口文档
+    <p>Apollo配置中心OpenAPI接口文档</p>
 
-    ## 认证方式
+    <h2>认证方式</h2>
+    <p>所有 API 接口都需要通过 <code>Authorization</code> header 进行身份验证。</p>
 
-    所有API接口都需要通过Authorization header进行身份验证。
+    <h3>获取 Token 的方式：</h3>
+    <ol>
+      <li><b>Portal 管理界面获取</b>：登录 Portal → 管理员工具 → 开放平台授权管理 → 创建第三方应用，获取 Token。</li>
+      <li><b>Token 格式</b>：<code>Authorization: token_value</code></li>
+      <li><b>Token 权限</b>：按应用/环境/命名空间授予，建议不同用途分别创建。</li>
+    </ol>
 
-    ### 获取Token的方式：
+    <h3>使用示例</h3>
+    <pre><code class="language-bash">curl -X GET "http://localhost:8070/openapi/v1/apps" \
+    -H "Authorization: your_token_here"</code></pre>
 
-    1. **Portal管理界面获取**：
-       - 登录Apollo Portal管理界面
-       - 进入"管理员工具" -> "开放平台授权管理"
-       - 创建第三方应用，获取Token
-
-    2. **Token格式**：
-       ```
-       Authorization: token_value
-       ```
-
-    3. **Token权限**：
-       - Token具有对应应用的读写权限
-       - 不同Token可能有不同的环境和命名空间权限
-       - 建议为不同用途创建不同的Token
-
-    ### 使用示例：
-    ```bash
-    curl -X GET "http://localhost:8070/openapi/v1/apps" \
-         -H "Authorization: your_token_here"
-    ```
   version: 1.0.0
 security:
   - ApiKeyAuth: []
@@ -53,7 +41,8 @@ tags:
 paths:
   /openapi/v1/apps:
     post:
-      summary: 创建应用
+      summary: 创建应用 (original openapi) # which means this belongs to initial openapi endpoints and should not be modified this time
+      operationId: createApp
       deprecated: false
       description: POST /openapi/v1/apps
       tags:
@@ -62,24 +51,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenCreateAppDTO'
-              required:
-                - app
-                - admins
-                - assignAppRoleToSelf
-              properties:
-                app:
-                  allOf:
-                    - $ref: '#/components/schemas/OpenAppDTO'
-                  required:
-                    - appId
-                    - name
-                    - orgId
-                    - orgName
-                    - ownerName
-              description: ''
+              $ref: '#/components/schemas/OpenCreateAppDTO' # this is for avoiding openapi-generator of generating a new schema(OpenAppDTO with restriction)
         required: true
       responses:
         '200':
@@ -106,42 +78,34 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-                  exception:
-                    type: string
-              example:
-                message: 'App is null'
-                exception: 'BadRequestException'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse' # This is to avoid openapi-generator generating completely different error responses for each error
         '403':
-          description: '权限不足'
+          description: 权限不足
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     get:
-      summary: 获取当前Consumer授权的应用列表
+      summary: 查找应用 (original openapi)
+      operationId: findApps
       deprecated: false
-      description: GET /openapi/v1/apps?authorized=true
+      description: POST /openapi/v1/apps
       tags:
         - App Management
       parameters:
-        - name: authorized
+        - name: appIds
           in: query
-          description: '是否只返回授权的应用'
+          description: 查找应用
           required: false
-          example: 'true'
+          example: '123'
           schema:
             type: string
       responses:
         '200':
-          description: '成功获取授权应用列表'
+          description: 成功获取应用列表
           content:
             application/json:
               schema:
@@ -176,22 +140,67 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
+  /openapi/v1/apps/authorized:
+    get:
+      summary: 获取当前Consumer授权的应用列表 (original openapi)
+      operationId: findAppsAuthorized
+      deprecated: false
+      description: GET /openapi/v1/apps/authorized
+      tags:
+        - App Management
+      responses:
+        '200':
+          description: 成功获取授权应用列表
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/OpenAppDTO'
               example:
-                message: 'Unauthorized'
-  /openapi/v1/apps/{appId}/env-clusters:
+                - dataChangeCreatedBy: 'apollo'
+                  dataChangeLastModifiedBy: 'apollo'
+                  dataChangeCreatedTime: '2024-01-15T10:30:00.000Z'
+                  dataChangeLastModifiedTime: '2024-01-15T10:30:00.000Z'
+                  name: 'Sample Application'
+                  appId: 'sample-app'
+                  orgId: 'default'
+                  orgName: 'Default Organization'
+                  ownerName: 'Apollo Admin'
+                  ownerEmail: 'admin@apollo.com'
+                - dataChangeCreatedBy: 'apollo'
+                  dataChangeLastModifiedBy: 'apollo'
+                  dataChangeCreatedTime: '2024-01-10T14:20:00.000Z'
+                  dataChangeLastModifiedTime: '2024-01-12T16:45:00.000Z'
+                  name: 'User Service'
+                  appId: 'user-service'
+                  orgId: 'microservices'
+                  orgName: 'Microservices Team'
+                  ownerName: 'Dev Team'
+                  ownerEmail: 'dev@company.com'
+          headers: { }
+        '401':
+          description: '未授权访问'
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
+  /openapi/v1/apps/{appId}/envclusters:
     get:
-      summary: 获取应用的环境集群信息
+      summary: 获取应用的环境集群信息 (original openapi)
+      operationId: getEnvClusterInfo
       deprecated: false
-      description: GET /openapi/v1/apps/{appId}/env-clusters
+      description: GET /openapi/v1/apps/{appId}/envclusters
       tags:
         - App Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: 应用ID
           required: true
           schema:
             type: string
@@ -223,14 +232,12 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App not found: invalid-app-id'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/apps/{appId}:
     get:
-      summary: 获取单个应用信息
+      summary: 获取单个应用信息(new added) # which means this is a new added openapi endpoint
+      operationId: getApp
       deprecated: false
       description: GET /openapi/v1/apps/{appId}
       tags:
@@ -267,13 +274,11 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App not found: invalid-app-id'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     put:
-      summary: 更新应用
+      summary: 更新应用(new added)
+      operationId: updateApp
       deprecated: false
       description: PUT /openapi/v1/apps/{appId}
       tags:
@@ -281,7 +286,7 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
@@ -289,20 +294,11 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenAppDTO'
-              required:
-                - appId
-                - name
-                - orgId
-                - orgName
-                - ownerName
-              description: ''
+              $ref: '#/components/schemas/OpenAppDTO'
         required: true
       responses:
         '200':
-          description: ''
+          description: '应用更新成功'
           content:
             application/json:
               schema:
@@ -325,24 +321,19 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Invalid app data'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     delete:
-      summary: 删除应用
+      summary: 删除应用(new added)
+      operationId: deleteApp
       deprecated: false
       description: DELETE /openapi/v1/apps/{appId}
       tags:
@@ -350,7 +341,7 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
@@ -361,41 +352,48 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App deleted successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '403':
           description: '权限不足，需要超级管理员权限'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '404':
           description: '应用不存在'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App not found: invalid-app-id'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
   /openapi/v1/apps/by-self:
     get:
-      summary: 获取当前Consumer的应用列表（分页）
+      summary: 获取当前Consumer的应用列表（分页）(new added)
+      operationId: getAppsBySelf
       deprecated: false
       description: GET /openapi/v1/apps/by-self
       tags:
         - App Management
+      parameters:
+        - name: page
+          in: query
+          description: '页数'
+          required: true
+          schema:
+            type: integer
+            minimum: 0
+        - name: size
+          in: query
+          description: '页大小'
+          required: true
+          schema:
+            type: integer
+            minimum: 0
       responses:
         '200':
           description: '成功获取Consumer的应用列表'
@@ -433,14 +431,12 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Unauthorized'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/apps/{appId}/navtree:
     get:
-      summary: 获取应用导航树
+      summary: 获取应用导航树(new added)
+      operationId: getAppNavTree
       deprecated: false
       description: GET /openapi/v1/apps/{appId}/navtree
       tags:
@@ -448,7 +444,7 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
@@ -460,7 +456,7 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/EnvClusterInfo'
+                  $ref: '#/components/schemas/OpenEnvClusterInfo'
               example:
                 - env: 'DEV'
                   clusters:
@@ -478,7 +474,8 @@ paths:
           headers: {}
   /openapi/v1/apps/envs/{env}:
     post:
-      summary: 在指定环境创建应用
+      summary: 在指定环境创建应用(new added)
+      operationId: createAppInEnv
       deprecated: false
       description: POST /openapi/v1/apps/envs/{env}
       tags:
@@ -486,7 +483,7 @@ paths:
       parameters:
         - name: env
           in: path
-          description: ''
+          description: 环境标识，例如 DEV、FAT、UAT、PROD
           required: true
           schema:
             type: string
@@ -494,16 +491,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenAppDTO'
-              required:
-                - appId
-                - name
-                - orgId
-                - orgName
-                - ownerName
-              description: ''
+              $ref: '#/components/schemas/OpenAppDTO'
         required: true
       responses:
         '200':
@@ -512,37 +500,29 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App created in environment successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '请求参数错误'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'appId should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
   /openapi/v1/apps/{appId}/miss_envs:
     get:
-      summary: 查找缺失的环境
+      summary: 查找缺失的环境(new added)
+      operationId: findMissEnvs
       deprecated: false
       description: GET /openapi/v1/apps/{appId}/miss_envs
       tags:
@@ -550,7 +530,7 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
@@ -563,9 +543,6 @@ paths:
                 type: array
                 items:
                   type: string
-              example:
-                - 'UAT'
-                - 'PRO'
           headers: {}
         '404':
           description: '应用不存在'
@@ -573,48 +550,44 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'App not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}:
     get:
-      summary: 获取单个配置项
+      summary: 获取单个配置项 (original openapi)
+      operationId: getItem
       deprecated: false
-      description: >-
-        GET
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: key
           in: path
-          description: ''
+          description: '配置项键名'
           required: true
           schema:
             type: string
@@ -641,17 +614,13 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     put:
-      summary: 更新配置项
+      summary: 更新配置项 (original openapi)
+      operationId: updateItem
       deprecated: false
-      description: >-
-        PUT
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
+      description: PUT /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
       tags:
         - Item Management
       parameters:
@@ -663,19 +632,19 @@ paths:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
@@ -692,18 +661,12 @@ paths:
           example: 'false'
           schema:
             type: boolean
+            default: false
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenItemDTO'
-              required:
-                - key
-                - dataChangeLastModifiedBy
-                - value
-              description: ''
+              $ref: '#/components/schemas/OpenItemDTO'
         required: true
       responses:
         '200':
@@ -712,145 +675,136 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item updated successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '请求参数错误'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'key, value and dataChangeLastModifiedBy should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '404':
           description: '配置项不存在'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
     delete:
-      summary: 删除配置项
+      summary: 删除配置项 (original openapi)
+      operationId: deleteItem
       deprecated: false
-      description: >-
-        DELETE
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
+      description: DELETE /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: key
           in: path
-          description: ''
+          description: '配置项键名'
           required: true
           schema:
             type: string
         - name: operator
           in: query
-          description: ''
-          required: true
+          description: '操作人用户名'
+          required: false
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '配置项删除成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:
     get:
-      summary: 获取命名空间下的配置项列表
+      summary: 获取命名空间下的配置项列表 (original openapi)
+      operationId: findItemsByNamespace
       deprecated: false
-      description: ''
+      description: 获取指定命名空间的配置项列表，支持分页
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: page
           in: query
-          description: ''
+          description: '页码，从0开始'
           required: true
           example: 0
           schema:
             type: integer
+            minimum: 0
         - name: size
           in: query
-          description: ''
+          description: '每页数量'
           required: true
           example: 50
           schema:
             type: integer
+            minimum: 0
       responses:
         '200':
           description: '成功获取配置项列表'
@@ -894,41 +848,37 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Namespace not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     post:
-      summary: 创建新的配置项
+      summary: 创建新的配置项 (original openapi)
+      operationId: createItem
       deprecated: false
-      description: >-
-        POST
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items
+      description: POST /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
@@ -936,14 +886,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenItemDTO'
-              required:
-                - key
-                - dataChangeCreatedBy
-                - value
-              description: ''
+              $ref: '#/components/schemas/OpenItemDTO'
         required: true
       responses:
         '200':
@@ -968,29 +911,22 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'key and dataChangeCreatedBy should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}:
     get:
-      summary: 通过查询参数获取配置项（支持编码的key）
+      summary: 通过查询参数获取配置项（支持编码的key） (original openapi)
+      operationId: getItemByEncodedKey
       deprecated: false
-      description: >-
-        GET
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items?key={key}&encoded={true|false}
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}
       tags:
         - Item Management
       parameters:
@@ -1002,25 +938,25 @@ paths:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: key
           in: path
-          description: ''
+          description: '配置项键名（需要URL编码）'
           required: true
           schema:
             type: string
@@ -1047,69 +983,59 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     put:
-      summary: 通过编码的key更新配置项
+      summary: 通过编码的key更新配置项 (original openapi)
+      operationId: updateItemByEncodedKey
       deprecated: false
-      description: >-
-        PUT
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}
+      description: PUT /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: key
           in: path
-          description: ''
+          description: '配置项键名（需要URL编码）'
           required: true
           schema:
             type: string
         - name: createIfNotExists
           in: query
-          description: ''
+          description: '若不存在则创建（true/false）'
           required: true
           example: 'false'
           schema:
             type: boolean
+            default: false
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenItemDTO'
-              required:
-                - key
-                - dataChangeLastModifiedBy
-                - value
-              description: ''
+              $ref: '#/components/schemas/OpenItemDTO'
         required: true
       responses:
         '200':
@@ -1118,51 +1044,38 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item updated successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
-          description: '请求参数错误'
+          description: 请求参数错误
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'key, value and dataChangeLastModifiedBy should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '404':
           description: '配置项不存在'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration item not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
     delete:
-      summary: 通过编码的key删除配置项
+      summary: 通过编码的key删除配置项 (original openapi)
+      operationId: deleteItemByEncodedKey
       deprecated: false
-      description: >-
-        DELETE
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}
+      description: DELETE /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/encodedItems/{key}
       tags:
         - Item Management
       parameters:
@@ -1199,7 +1112,7 @@ paths:
         - name: operator
           in: query
           description: ''
-          required: true
+          required: false
           schema:
             type: string
       responses:
@@ -1209,15 +1122,17 @@ paths:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:batchUpdate:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/batchUpdate:
     put:
-      summary: 通过文本批量修改配置项
+      summary: 通过文本批量修改配置项 (new added)
+      operationId: batchUpdateItemsByText
       deprecated: false
       description: >-
         PUT
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:batchUpdate
+        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/batchUpdate:
       tags:
         - Item Management
       parameters:
@@ -1249,14 +1164,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceTextModel'
-              required:
-                - operator
-                - format
-                - configText
-              description: ''
+              $ref: '#/components/schemas/OpenNamespaceTextModel'
         required: true
       responses:
         '200':
@@ -1265,71 +1173,55 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Batch update configuration items successfully'
-        '400':
-          description: '请求参数错误'
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'operator should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/items:
     get:
-      summary: 获取分支下的配置项
+      summary: 获取分支下的配置项 (new added)
+      operationId: getBranchItems
       deprecated: false
       description: >-
         GET
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/items
+        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/items:
       tags:
-        - Namespace Branch Management
+        - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
@@ -1366,42 +1258,40 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Branch not found'
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:compare:
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/compare:
     post:
-      summary: 对比命名空间配置差异
+      summary: 对比命名空间配置差异 (new added)
+      operationId: compareItems
       deprecated: false
       description: >-
         POST
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:compare
+        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/compare
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
@@ -1409,13 +1299,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceSyncModel'
-              required:
-                - syncToNamespaces
-                - syncItems
-              description: ''
+              $ref: '#/components/schemas/OpenNamespaceSyncModel'
         required: true
       responses:
         '200':
@@ -1425,7 +1309,7 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ListItemDiffs'
+                  $ref: '#/components/schemas/OpenItemDiffs'
               example:
                 - namespace:
                     appId: ''
@@ -1483,25 +1367,26 @@ paths:
                         lineNum: 0
                   extInfo: ''
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:sync:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/sync:
     post:
-      summary: 同步配置项到多个命名空间
+      summary: 同步配置项到多个命名空间 (new added)
+      operationId: syncItems
       deprecated: false
       description: >-
         POST
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:sync
+        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/sync:
       tags:
         - Item Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
@@ -1521,13 +1406,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceSyncModel'
-              required:
-                - syncToNamespaces
-                - syncItems
-              description: ''
+              $ref: '#/components/schemas/OpenNamespaceSyncModel'
         required: true
       responses:
         '200':
@@ -1536,41 +1415,33 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration items synced successfully to target namespaces'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '请求参数错误'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'syncToNamespaces should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:validate:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/validate:
     post:
-      summary: 验证配置文本语法
+      summary: 验证配置文本语法 (new added)
+      operationId: validateItems
       deprecated: false
       description: >-
         POST
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:validate
+        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/validate
       tags:
         - Item Management
       parameters:
@@ -1602,13 +1473,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceTextModel'
-              required:
-                - format
-                - configText
-              description: ''
+              $ref: '#/components/schemas/OpenNamespaceTextModel'
         required: true
       responses:
         '200':
@@ -1617,43 +1482,25 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  valid:
-                    type: boolean
-                  message:
-                    type: string
-              example:
-                valid: true
-                message: 'Configuration syntax is valid'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '配置文本语法错误'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  valid:
-                    type: boolean
-                  message:
-                    type: string
-                  errors:
-                    type: array
-                    items:
-                      type: string
-              example:
-                valid: false
-                message: 'Configuration syntax validation failed'
-                errors:
-                  - 'Line 3: Invalid property format'
-                  - 'Line 7: Missing value for key "database.port"'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:revert:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/revert:
     post:
-      summary: 撤销配置项更改
+      summary: 撤销配置项更改 (new added)
+      operationId: revertItems
       deprecated: false
       description: >-
         POST
-        /apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items:revert
+        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/revert
       tags:
         - Item Management
       parameters:
@@ -1688,39 +1535,31 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Configuration changes reverted successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '请求参数错误'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Invalid revert request'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
-  /openapi/v1/apps/{appId}/clusters/{clusterName}:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}:
     get:
-      summary: 获取指定集群信息
+      summary: 获取指定集群信息 (original openapi)
+      operationId: getCluster
       deprecated: false
-      description: GET /openapi/v1/apps/{appId}/clusters/{clusterName}
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}
       tags:
         - Cluster Management
       parameters:
@@ -1736,99 +1575,38 @@ paths:
           required: true
           schema:
             type: string
-      responses:
-        '200':
-          description: '成功获取集群信息'
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OpenClusterDTO'
-              example:
-                dataChangeCreatedBy: 'apollo'
-                dataChangeLastModifiedBy: 'ops-user'
-                dataChangeCreatedTime: '2024-01-15T10:30:00.000Z'
-                dataChangeLastModifiedTime: '2024-01-18T09:15:00.000Z'
-                name: 'production'
-                appId: 'sample-app'
-          headers: {}
-        '404':
-          description: '集群不存在'
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Cluster not found'
-  /openapi/v1/apps/{appId}/clusters:
-    post:
-      summary: 创建集群
-      deprecated: false
-      description: POST /openapi/v1/apps/{appId}/clusters
-      tags:
-        - Cluster Management
-      parameters:
-        - name: appId
+        - name: env
           in: path
           description: ''
           required: true
           schema:
             type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenClusterDTO'
-              required:
-                - name
-                - appId
-                - dataChangeCreatedBy
-              description: ''
-        required: true
       responses:
         '200':
-          description: '集群创建成功'
+          description: 成功获取集群信息
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/OpenClusterDTO'
               example:
-                dataChangeCreatedBy: 'apollo'
-                dataChangeLastModifiedBy: 'apollo'
+                dataChangeCreatedBy: apollo
+                dataChangeLastModifiedBy: ops-user
                 dataChangeCreatedTime: '2024-01-15T10:30:00.000Z'
-                dataChangeLastModifiedTime: '2024-01-15T10:30:00.000Z'
-                name: 'test-cluster'
-                appId: 'sample-app'
+                dataChangeLastModifiedTime: '2024-01-18T09:15:00.000Z'
+                name: production
+                appId: sample-app
           headers: {}
-        '400':
-          description: '请求参数错误'
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'name and dataChangeCreatedBy should not be null or empty'
-        '403':
-          description: '权限不足'
+        '404':
+          description: 集群不存在
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}:
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     delete:
-      summary: 删除集群
+      summary: 删除集群 (new added)
+      operationId: deleteCluster
       deprecated: false
       description: DELETE /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}
       tags:
@@ -1859,74 +1637,50 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Cluster deleted successfully'
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
         '400':
           description: '删除失败，集群可能包含配置'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Cannot delete cluster with existing configurations'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '404':
           description: '集群不存在'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Cluster not found'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters:
     post:
-      summary: 创建发布
+      summary: 创建集群 (original openapi)
+      operationId: createCluster
       deprecated: false
-      description: ''
+      description: POST /openapi/v1/envs/{env}/apps/{appId}/clusters
       tags:
-        - Release Management
+        - Cluster Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: 应用ID
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
-          required: true
-          schema:
-            type: string
-        - name: clusterName
-          in: path
-          description: ''
-          required: true
-          schema:
-            type: string
-        - name: namespaceName
-          in: path
-          description: ''
           required: true
           schema:
             type: string
@@ -1934,31 +1688,95 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceReleaseDTO'
-              required:
-                - releaseTitle
-                - releasedBy
-              description: ''
+              $ref: '#/components/schemas/OpenClusterDTO'
         required: true
       responses:
         '200':
-          description: '发布创建成功'
+          description: 集群创建成功
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/OpenReleaseDTO'
+                $ref: '#/components/schemas/OpenClusterDTO'
               example:
-                dataChangeCreatedBy: 'apollo'
-                dataChangeLastModifiedBy: 'apollo'
+                dataChangeCreatedBy: apollo
+                dataChangeLastModifiedBy: apollo
                 dataChangeCreatedTime: '2024-01-15T10:30:00.000Z'
                 dataChangeLastModifiedTime: '2024-01-15T10:30:00.000Z'
-                id: 12345
-                appId: 'sample-app'
-                clusterName: 'default'
-                namespaceName: 'application'
-                name: 'Release v1.0.0'
+                name: test-cluster
+                appId: sample-app
+          headers: {}
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
+        '403':
+          description: 权限不足
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases:
+    post:
+      summary: 创建发布 (original openapi)
+      operationId: createRelease
+      deprecated: false
+      description: '创建发布'
+      tags:
+        - Release Management
+      parameters:
+        - name: appId
+          in: path
+          description: 'app标识'
+          required: true
+          schema:
+            type: string
+        - name: env
+          in: path
+          description: '环境标识'
+          required: true
+          schema:
+            type: string
+        - name: clusterName
+          in: path
+          description: ''
+          required: true
+          schema:
+            type: string
+        - name: namespaceName
+          in: path
+          description: 命名空间名称
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NamespaceReleaseDTO'
+        required: true
+      responses:
+        '200':
+          description: 发布创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpenReleaseDTO'
+              example:
+                dataChangeCreatedBy: 'apollo'
+                dataChangeLastModifiedBy: 'apollo'
+                dataChangeCreatedTime: '2024-01-15T10:30:00.000Z'
+                dataChangeLastModifiedTime: '2024-01-15T10:30:00.000Z'
+                id: 12345
+                appId: 'sample-app'
+                clusterName: 'default'
+                namespaceName: 'application'
+                name: 'Release v1.0.0'
                 configurations:
                   'server.port': '8080'
                   'spring.datasource.url': 'jdbc:mysql://localhost:3306/apollo'
@@ -1971,51 +1789,46 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Params(releaseTitle and releasedBy) can not be empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases/latest:
     get:
-      summary: 获取最新活跃发布
+      summary: 获取最新活跃发布 (original openapi)
+      operationId: loadLatestActiveRelease
       deprecated: false
-      description: ''
+      description: '查询命名空间最新活跃发布'
       tags:
         - Release Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
@@ -2049,52 +1862,50 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'No active release found for this namespace'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/merge:
     post:
-      summary: 合并分支
+      summary: 合并分支 (original openapi)
+      operationId: merge
       deprecated: false
-      description: ''
+      description: '合并灰度分支并可选择删除分支'
       tags:
-        - Namespace Branch Management
+        - Release Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
         - name: deleteBranch
           in: query
-          description: ''
+          description: '合并后是否删除分支（true/false）'
           required: true
           example: 'true'
           schema:
@@ -2103,13 +1914,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceReleaseDTO'
-              required:
-                - releaseTitle
-                - releasedBy
-              description: ''
+              $ref: '#/components/schemas/NamespaceReleaseDTO'
         required: true
       responses:
         '200':
@@ -2141,57 +1946,52 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'releaseTitle and releasedBy should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/releases:
     post:
-      summary: 创建灰度发布
+      summary: 创建灰度发布 (original openapi)
+      operationId: createGrayRelease
       deprecated: false
-      description: ''
+      description: '创建灰度发布'
       tags:
-        - Namespace Branch Management
+        - Release Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: 'app标识'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
@@ -2199,17 +1999,11 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceReleaseDTO'
-              required:
-                - releaseTitle
-                - releasedBy
-              description: ''
+              $ref: '#/components/schemas/NamespaceReleaseDTO'
         required: true
       responses:
         '200':
-          description: ''
+          description: 灰度发布创建成功
           content:
             application/json:
               schema:
@@ -2230,11 +2024,12 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/gray-del-releases:
     post:
-      summary: 创建灰度删除发布
+      summary: 创建灰度删除发布 (original openapi)
+      operationId: createGrayDelRelease
       deprecated: false
       description: ''
       tags:
-        - Namespace Branch Management
+        - Release Management
       parameters:
         - name: appId
           in: path
@@ -2270,14 +2065,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceGrayDelReleaseDTO'
-              required:
-                - releaseTitle
-                - releasedBy
-                - grayDelKeys
-              description: ''
+              $ref: '#/components/schemas/NamespaceGrayDelReleaseDTO'
         required: true
       responses:
         '200':
@@ -2302,42 +2090,46 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/releases/{releaseId}/rollback:
     put:
-      summary: 回滚发布
+      summary: 回滚发布 (original openapi)
+      operationId: rollback
       deprecated: false
-      description: ''
+      description: 回滚到指定的发布版本
       tags:
         - Release Management
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: releaseId
           in: path
-          description: ''
+          description: '发布ID'
           required: true
           schema:
             type: integer
+            format: int64
         - name: operator
           in: query
-          description: ''
-          required: true
+          description: '操作人用户名'
+          required: false
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '发布回滚成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
   /openapi/v1/envs/{env}/releases/{releaseId}:
     get:
-      summary: 获取发布详情
+      summary: 获取发布详情 (new added)
+      operationId: getReleaseById
       deprecated: false
       description: GET /openapi/v1/envs/{env}/releases/{releaseId}
       tags:
@@ -2345,19 +2137,19 @@ paths:
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: releaseId
           in: path
-          description: ''
+          description: '发布ID'
           required: true
           schema:
             type: integer
       responses:
         '200':
-          description: ''
+          description: '成功获取发布详情'
           content:
             application/json:
               schema:
@@ -2378,7 +2170,8 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases/all:
     get:
-      summary: 获取所有发布（分页）
+      summary: 获取所有发布（分页） (new added)
+      operationId: findAllReleases
       deprecated: false
       description: >-
         GET
@@ -2388,51 +2181,51 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: page
           in: query
-          description: ''
+          description: '页码，从0开始'
           required: true
           example: 0
           schema:
             type: integer
         - name: size
           in: query
-          description: ''
+          description: '每页数量'
           required: true
           example: 5
           schema:
             type: integer
       responses:
         '200':
-          description: ''
+          description: '成功获取发布列表'
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ListReleaseBO'
+                  $ref: '#/components/schemas/OpenReleaseBO'
               example:
                 - baseInfo:
                     dataChangeCreatedBy: ''
@@ -2456,7 +2249,8 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases/active:
     get:
-      summary: 获取活跃发布（分页）
+      summary: 获取活跃发布（分页） (new added)
+      operationId: findActiveReleases
       deprecated: false
       description: >-
         GET
@@ -2466,45 +2260,45 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: page
           in: query
-          description: ''
+          description: '页码，从0开始'
           required: true
           example: 0
           schema:
             type: integer
         - name: size
           in: query
-          description: ''
+          description: '每页数量'
           required: true
           example: 5
           schema:
             type: integer
       responses:
         '200':
-          description: ''
+          description: '成功获取活跃发布列表'
           content:
             application/json:
               schema:
@@ -2525,86 +2319,41 @@ paths:
                     '': ''
                   comment: ''
           headers: {}
-  /openapi/v1/envs/{env}/releases/compare:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances:
     get:
-      summary: 对比发布
+      summary: 获取命名空间下的实例数量 (original openapi)
+      operationId: getInstanceCountByNamespace
       deprecated: false
-      description: GET /openapi/v1/envs/{env}/releases/compare
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances
       tags:
-        - Release Management
+        - Instance Management
       parameters:
         - name: env
           in: path
-          description: ''
           required: true
           schema:
             type: string
-        - name: baseReleaseId
-          in: query
-          description: ''
-          required: true
-          schema:
-            type: integer
-        - name: toCompareReleaseId
-          in: query
-          description: ''
-          required: true
-          schema:
-            type: integer
-      responses:
-        '200':
-          description: ''
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  changes:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Change'
-              example:
-                changes:
-                  - type: ''
-                    entity:
-                      firstEntity:
-                        key: ''
-                        value: ''
-                      secondEntity:
-                        key: ''
-                        value: ''
-          headers: {}
-  /openapi/v1/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances:
-    get:
-      summary: 获取命名空间下的实例数量
-      deprecated: false
-      description: >-
-        GET
-        /openapi/v1/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances
-      tags:
-        - Instance Management
-      parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功返回实例数量'
           content:
             application/json:
               schema:
@@ -2612,7 +2361,7 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/releases/{releaseId}/instances:
     get:
-      summary: 根据发布版本查询实例（支持分页）
+      summary: 根据发布版本查询实例（支持分页） (new added)
       deprecated: false
       description: GET /openapi/v1/envs/{env}/releases/{releaseId}/instances
       tags:
@@ -2679,9 +2428,9 @@ paths:
                         dataChangeLastModifiedTime: ''
                     dataChangeCreatedTime: ''
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/instances_not_int: # avoidng confliction with other server endpoint
     get:
-      summary: 查询不在指定发布版本中的实例
+      summary: 查询不在指定发布版本中的实例 (new added)
       deprecated: false
       description: >-
         GET
@@ -2691,25 +2440,25 @@ paths:
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
@@ -2754,7 +2503,8 @@ paths:
           headers: {}
   /openapi/v1/apps/{appId}/appnamespaces:
     post:
-      summary: 创建AppNamespace
+      summary: 创建AppNamespace (original openapi)
+      operationId: createNamespace
       deprecated: false
       description: POST /openapi/v1/apps/{appId}/appnamespaces
       tags:
@@ -2770,15 +2520,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenAppNamespaceDTO'
-              required:
-                - appId
-                - name
-                - format
-                - dataChangeCreatedBy
-              description: ''
+              $ref: '#/components/schemas/OpenAppNamespaceDTO'
         required: true
       responses:
         '200':
@@ -2805,24 +2547,19 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'appId, name, format and dataChangeCreatedBy should not be null or empty'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
         '403':
           description: '权限不足'
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Access is denied'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     get:
-      summary: 获取指定应用的AppNamespace
+      summary: 获取指定应用的AppNamespace (new added)
+      operationId: getAppNamespacesByApp
       deprecated: false
       description: GET /openapi/v1/apps/{appId}/appnamespaces
       tags:
@@ -2857,11 +2594,10 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces:
     get:
-      summary: 获取指定集群下的所有Namespace
+      summary: 获取指定集群下的所有Namespace (original openapi)
+      operationId: findNamespaces
       deprecated: false
-      description: >-
-        GET
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces
       tags:
         - Namespace Management
       parameters:
@@ -2890,6 +2626,7 @@ paths:
           example: 'true'
           schema:
             type: boolean
+            default: true
       responses:
         '200':
           description: ''
@@ -2922,13 +2659,12 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}:
     get:
-      summary: 获取指定的Namespace
+      summary: 获取指定的Namespace (original openapi)
+      operationId: loadNamespace
       deprecated: false
-      description: >-
-        GET
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}
       tags:
-        - Cluster Management
+        - Namespace Management
       parameters:
         - name: appId
           in: path
@@ -2961,6 +2697,7 @@ paths:
           example: 'true'
           schema:
             type: boolean
+            default: true
       responses:
         '200':
           description: ''
@@ -2991,11 +2728,10 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/lock:
     get:
-      summary: 获取Namespace的锁状态
+      summary: 获取Namespace的锁状态 (original openapi)
+      operationId: getNamespaceLock
       deprecated: false
-      description: >-
-        GET
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/lock
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/lock
       tags:
         - Namespace Management
       parameters:
@@ -3037,7 +2773,8 @@ paths:
           headers: {}
   /openapi/v1/appnamespaces:
     get:
-      summary: 获取所有公共AppNamespace
+      summary: 获取所有公共AppNamespace (new added)
+      operationId: getAppNamespaces
       deprecated: false
       description: GET /openapi/v1/appnamespaces?public=true
       tags:
@@ -3073,7 +2810,8 @@ paths:
           headers: {}
   /openapi/v1/apps/{appId}/appnamespaces/{namespaceName}:
     get:
-      summary: 获取指定的AppNamespace
+      summary: 获取指定的AppNamespace (new added)
+      operationId: getAppNamespace
       deprecated: false
       description: GET /openapi/v1/apps/{appId}/appnamespaces/{namespaceName}
       tags:
@@ -3081,19 +2819,19 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功获取AppNamespace'
           content:
             application/json:
               schema:
@@ -3111,65 +2849,62 @@ paths:
                 comment: ''
           headers: {}
     delete:
-      summary: 删除AppNamespace
+      summary: 删除AppNamespace (new added)
+      operationId: deleteAppNamespace
       deprecated: false
       description: DELETE /openapi/v1/apps/{appId}/appnamespaces/{namespaceName}
       tags:
-        - App Management
+        - Namespace Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: 'AppNamespace删除成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
   /openapi/v1/apps/{appId}/namespaces/releases/status:
     get:
-      summary: 获取应用下所有Namespace的发布状态
+      summary: 获取应用下所有Namespace的发布状态 (new added)
+      operationId: getNamespacesReleaseStatus
       deprecated: false
       description: GET /openapi/v1/apps/{appId}/namespaces/releases/status
       tags:
-        - App Management
+        - Namespace Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功获取发布状态映射'
           content:
             application/json:
               schema:
-                type: object
-                additionalProperties:
-                  type: object
-                  additionalProperties:
-                    type: boolean
-              example:
-                '':
-                  '': false
+                $ref: '#/components/schemas/StringToStringBoolMap'
           headers: {}
   /openapi/v1/envs/{env}/appnamespaces/{publicNamespaceName}/instances:
     get:
-      summary: 获取公共AppNamespace的所有实例
+      summary: 获取公共AppNamespace的所有实例 (new added)
+      operationId: getPublicAppNamespaceInstances
       deprecated: false
       description: GET /openapi/v1/envs/{env}/appnamespaces/{publicNamespaceName}/instances
       tags:
@@ -3177,33 +2912,33 @@ paths:
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: publicNamespaceName
           in: path
-          description: ''
+          description: '公共命名空间名称'
           required: true
           schema:
             type: string
         - name: page
           in: query
-          description: ''
+          description: '页码，从0开始'
           required: true
           example: 0
           schema:
             type: integer
         - name: size
           in: query
-          description: ''
+          description: '每页数量'
           required: true
           example: 10
           schema:
             type: integer
       responses:
         '200':
-          description: ''
+          description: '成功获取实例列表'
           content:
             application/json:
               schema:
@@ -3233,7 +2968,8 @@ paths:
           headers: {}
   /openapi/v1/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/public-association:
     get:
-      summary: 获取关联的公共Namespace
+      summary: 获取关联的公共Namespace (new added)
+      operationId: getPublicNamespaceAssociation
       deprecated: false
       description: >-
         GET
@@ -3243,31 +2979,31 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功获取关联的公共Namespace'
           content:
             application/json:
               schema:
@@ -3295,7 +3031,8 @@ paths:
           headers: {}
   /openapi/v1/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/integrity-check:
     get:
-      summary: 检查缺失的Namespace
+      summary: 检查缺失的Namespace (new added)
+      operationId: checkNamespaceIntegrity
       deprecated: false
       description: >-
         GET
@@ -3305,25 +3042,25 @@ paths:
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '缺失的命名空间名称列表'
           content:
             application/json:
               schema:
@@ -3335,50 +3072,53 @@ paths:
           headers: {}
   /openapi/v1/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/links:
     delete:
-      summary: 删除关联的Namespace
+      summary: 删除关联的Namespace (new added)
+      operationId: deleteNamespaceLinks
       deprecated: false
       description: >-
         DELETE
         /openapi/v1/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/links
       tags:
-        - App Management
+        - Namespace Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '解除关联成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
   /openapi/v1/organizations:
     get:
-      summary: 获取所有组织信息
+      summary: 获取所有组织信息 (original openapi)
+      operationId: getOrganization
       deprecated: false
       description: GET /openapi/v1/organizations
       tags:
@@ -3407,48 +3147,44 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Unauthorized'
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches:
     get:
-      summary: 获取命名空间分支信息
+      summary: 获取命名空间分支信息 (original openapi)
+      operationId: findBranch
       deprecated: false
-      description: >-
-        GET
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches
       tags:
-        - Cluster Management
+        - Namespace Branch Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功获取分支信息'
           content:
             application/json:
               schema:
@@ -3488,54 +3224,49 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  message:
-                    type: string
-              example:
-                message: 'Branch not found for this namespace'
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branch:
+                allOf:
+                  - $ref: '#/components/schemas/ExceptionResponse'
     post:
-      summary: 创建命名空间分支
+      summary: 创建命名空间分支 (original openapi)
       deprecated: false
-      description: >-
-        POST
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branch
+      operationId: createBranch
+      description: POST /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches
       tags:
         - Namespace Branch Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: 'app标识'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: operator
           in: query
-          description: ''
-          required: true
+          description: '操作人用户名'
+          required: false
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '命名空间分支创建成功'
           content:
             application/json:
               schema:
@@ -3563,61 +3294,62 @@ paths:
           headers: {}
   /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}:
     delete:
-      summary: 删除命名空间分支
+      summary: 删除命名空间分支 (original openapi)
       deprecated: false
-      description: >-
-        DELETE
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}
+      operationId: deleteBranch
+      description: DELETE /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}
       tags:
         - Namespace Branch Management
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
         - name: operator
           in: query
-          description: ''
-          required: true
+          description: 操作人用户名
+          required: false
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '分支删除成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
     patch:
-      summary: 合并分支到主分支
+      summary: 合并分支到主分支 (new added)
+      operationId: mergeBranch
       deprecated: false
       description: >-
         PATCH
@@ -3630,62 +3362,50 @@ paths:
       parameters:
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
         - name: deleteBranch
           in: query
-          description: ''
+          description: '合并后是否删除分支（true/false）'
           required: true
           example: 'true'
           schema:
             type: boolean
-        - name: X-Apollo-Operator
-          in: header
-          description: ''
-          required: true
-          schema:
-            type: string
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/NamespaceReleaseDTO'
-              required:
-                - releaseTitle
-                - releasedBy
-              description: ''
+              $ref: '#/components/schemas/NamespaceReleaseDTO'
         required: true
       responses:
         '200':
-          description: ''
+          description: '分支合并成功'
           content:
             application/json:
               schema:
@@ -3704,49 +3424,48 @@ paths:
                   '': ''
                 comment: ''
           headers: {}
-  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/gray-rules:
+  /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/rules:
     get:
-      summary: 获取分支灰度发布规则
+      summary: 获取分支灰度发布规则 (original openapi)
+      operationId: getBranchGrayRules
       deprecated: false
-      description: >-
-        GET
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/gray-rules
+      description: GET /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/rules
       tags:
         - Namespace Branch Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: 'app标识'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
       responses:
         '200':
-          description: ''
+          description: '成功获取灰度发布规则'
           content:
             application/json:
               schema:
@@ -3768,69 +3487,64 @@ paths:
                       - ''
           headers: {}
     put:
-      summary: 更新分支灰度发布规则
+      summary: 更新分支灰度发布规则 (original openapi)
+      operationId: updateBranchRules
       deprecated: false
-      description: >-
-        PUT
-        /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/gray-rules
+      description: PUT /openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/rules
       tags:
         - Namespace Branch Management
       parameters:
         - name: appId
           in: path
-          description: ''
+          description: '应用ID'
           required: true
           schema:
             type: string
         - name: env
           in: path
-          description: ''
+          description: '环境标识'
           required: true
           schema:
             type: string
         - name: clusterName
           in: path
-          description: ''
+          description: '集群名称'
           required: true
           schema:
             type: string
         - name: namespaceName
           in: path
-          description: ''
+          description: '命名空间名称'
           required: true
           schema:
             type: string
         - name: branchName
           in: path
-          description: ''
+          description: '分支名称'
           required: true
           schema:
             type: string
         - name: operator
-          in: header
-          description: ''
-          required: true
+          in: query
+          description: 操作人用户名
+          required: false
           schema:
             type: string
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              allOf:
-                - $ref: '#/components/schemas/OpenGrayReleaseRuleDTO'
-              required:
-                - ruleItems
-              description: ''
+              $ref: '#/components/schemas/OpenGrayReleaseRuleDTO'
         required: true
       responses:
         '200':
-          description: ''
+          description: '灰度规则更新成功'
           content:
             application/json:
               schema:
                 type: object
-                properties: {}
+                allOf:
+                  - $ref: '#/components/schemas/SuccessEmptyResponse'
           headers: {}
 components:
   securitySchemes:
@@ -3865,9 +3579,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 数据创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 数据最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         name:
           type: string
           description: 应用名称，用于显示的友好名称
@@ -3900,7 +3616,6 @@ components:
           description: 应用管理员用户名列表。应用负责人默认具有项目管理员权限。管理员可以创建命名空间、集群并分配用户权限
         app:
           $ref: '#/components/schemas/OpenAppDTO'
-          description: 应用基本信息，包含应用的详细配置数据
       description: 创建Apollo应用的请求数据传输对象，包含创建应用所需的所有信息
     OpenItemDTO:
       type: object
@@ -3914,9 +3629,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 配置项创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 配置项最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         key:
           type: string
           description: 配置项的键名，在同一命名空间内唯一标识一个配置项
@@ -3947,7 +3664,6 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/OpenItemDTO'
-            description: com.ctrip.framework.apollo.openapi.dto.OpenItemDTO
           description: 当前页的配置项列表，包含具体的配置项数据
       description: 分页配置项数据传输对象，用于返回分页查询的配置项列表结果
     OpenClusterDTO:
@@ -3962,9 +3678,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 集群创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 集群最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         name:
           type: string
           description: 集群名称，在同一应用和环境下唯一标识一个集群
@@ -3974,10 +3692,8 @@ components:
       description: Apollo集群信息数据传输对象，表示应用在特定环境下的集群配置
     MapString:
       type: object
-      properties:
-        key:
-          type: string
-      description: 字符串映射对象，用于表示键值对的配置数据结构
+      additionalProperties:
+        type: string
     OpenReleaseDTO:
       type: object
       properties:
@@ -3990,9 +3706,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 发布创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 发布最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         id:
           type: integer
           description: 发布记录的唯一标识符，系统自动生成
@@ -4011,7 +3729,6 @@ components:
           description: 发布名称，用于标识这次发布的版本或描述
         configurations:
           $ref: '#/components/schemas/MapString'
-          description: 本次发布包含的所有配置项键值对
         comment:
           type: string
           description: 发布备注，描述本次发布的变更内容和目的
@@ -4065,9 +3782,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 命名空间创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 命名空间最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         name:
           type: string
           description: 命名空间名称，在同一应用内唯一标识一个命名空间
@@ -4117,9 +3836,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 灰度规则创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 灰度规则最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         appId:
           type: string
           description: 所属应用的唯一标识符
@@ -4136,7 +3857,6 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/OpenGrayReleaseRuleItemDTO'
-            description: com.ctrip.framework.apollo.openapi.dto.OpenGrayReleaseRuleItemDTO
           description: 灰度发布规则项列表，包含具体的灰度规则条件
       description: Apollo灰度发布规则数据传输对象，表示完整的灰度发布规则配置
     OpenNamespaceDTO:
@@ -4151,9 +3871,11 @@ components:
         dataChangeCreatedTime:
           type: string
           description: 命名空间创建时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
           description: 命名空间最后修改时间，ISO 8601格式的时间戳
+          example: "2025-09-29T12:34:56Z"
         appId:
           type: string
           description: 所属应用的唯一标识符
@@ -4215,371 +3937,228 @@ components:
       properties:
         env:
           type: string
-          description: ''
+          description: '环境标识，例如 DEV、FAT、UAT、PROD'
         clusters:
           type: array
           items:
             type: string
-          description: ''
-    ClusterDTO:
-      type: object
-      properties:
-        dataChangeCreatedBy:
-          type: string
-          description: ''
-        dataChangeLastModifiedBy:
-          type: string
-          description: ''
-        dataChangeCreatedByDisplayName:
-          type: string
-          description: ''
-        dataChangeLastModifiedByDisplayName:
-          type: string
-          description: ''
-        dataChangeCreatedTime:
-          type: string
-          description: ''
-        dataChangeLastModifiedTime:
-          type: string
-          description: ''
-        id:
-          type: integer
-          description: ''
-          format: int64
-        name:
-          type: string
-          description: ''
-          pattern: '[0-9a-zA-Z_-]+[0-9a-zA-Z_.-]*'
-        appId:
-          type: string
-          description: ''
-        parentClusterId:
-          type: integer
-          description: ''
-          format: int64
-        comment:
-          type: string
-          description: ''
-      required:
-        - name
-        - appId
-    EnvClusterInfo:
+          description: 该环境下的集群名称列表
+    OpenEnvClusterInfo:
       type: object
       properties:
         env:
           type: string
-          description: ''
+          description: '环境标识'
         clusters:
           type: array
           items:
-            $ref: '#/components/schemas/ClusterDTO'
-            description: com.ctrip.framework.apollo.common.dto.ClusterDTO
-          description: ''
-
-
-    NamespaceTextModel:
+            $ref: '#/components/schemas/OpenClusterDTO'
+          description: '集群信息列表'
+    OpenNamespaceTextModel:
       type: object
       properties:
         appId:
           type: string
-          description: ''
+          description: '应用唯一标识'
         env:
           type: string
-          description: ''
+          description: '环境标识'
         clusterName:
           type: string
-          description: ''
+          description: '集群名称'
         namespaceName:
           type: string
-          description: ''
+          description: '命名空间名称'
         namespaceId:
           type: integer
-          description: ''
+          description: '命名空间ID'
           format: int64
         format:
           type: string
-          description: ''
+          description: '命名空间格式类型（properties/xml/json/yml等）'
         configText:
           type: string
-          description: ''
+          description: '配置内容的原始文本'
         operator:
           type: string
-          description: ''
-    NamespaceIdentifier:
+          description: '操作者用户名'
+    OpenNamespaceIdentifier:
       type: object
       properties:
         appId:
           type: string
-          description: ''
+          description: '应用唯一标识'
         env:
           type: string
-          description: ''
+          description: '环境标识'
         clusterName:
           type: string
-          description: ''
+          description: '集群名称'
         namespaceName:
           type: string
-          description: ''
-    ItemDTO:
+          description: '命名空间名称'
+    OpenItemChangeSets:
       type: object
       properties:
         dataChangeCreatedBy:
           type: string
-          description: ''
+          description: '变更集合创建者用户名'
         dataChangeLastModifiedBy:
           type: string
-          description: ''
+          description: '变更集合最后修改者用户名'
         dataChangeCreatedByDisplayName:
           type: string
-          description: ''
+          description: '创建者显示名'
         dataChangeLastModifiedByDisplayName:
           type: string
-          description: ''
+          description: '最后修改者显示名'
         dataChangeCreatedTime:
           type: string
-          description: ''
+          description: '变更集合创建时间（ISO 8601）'
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
-          description: ''
-        id:
-          type: integer
-          description: ''
-          format: int64
-        namespaceId:
-          type: integer
-          description: ''
-          format: int64
-        key:
-          type: string
-          description: ''
-        type:
-          type: integer
-          description: ''
-        value:
-          type: string
-          description: ''
-        comment:
-          type: string
-          description: ''
-        lineNum:
-          type: integer
-          description: ''
-    ItemChangeSets:
-      type: object
-      properties:
-        dataChangeCreatedBy:
-          type: string
-          description: ''
-        dataChangeLastModifiedBy:
-          type: string
-          description: ''
-        dataChangeCreatedByDisplayName:
-          type: string
-          description: ''
-        dataChangeLastModifiedByDisplayName:
-          type: string
-          description: ''
-        dataChangeCreatedTime:
-          type: string
-          description: ''
-        dataChangeLastModifiedTime:
-          type: string
-          description: ''
+          description: '变更集合最后修改时间（ISO 8601）'
+          example: "2025-09-29T12:34:56Z"
         createItems:
           type: array
           items:
-            $ref: '#/components/schemas/ItemDTO'
-            description: com.ctrip.framework.apollo.common.dto.ItemDTO
-          description: ''
+            $ref: '#/components/schemas/OpenItemDTO'
+          description: '待创建的配置项列表'
           default: []
         updateItems:
           type: array
           items:
-            $ref: '#/components/schemas/ItemDTO'
-            description: com.ctrip.framework.apollo.common.dto.ItemDTO
-          description: ''
+            $ref: '#/components/schemas/OpenItemDTO'
+          description: '待更新的配置项列表'
           default: []
         deleteItems:
           type: array
           items:
-            $ref: '#/components/schemas/ItemDTO'
-            description: com.ctrip.framework.apollo.common.dto.ItemDTO
-          description: ''
+            $ref: '#/components/schemas/OpenItemDTO'
+          description: '待删除的配置项列表'
           default: []
-    ListItemDiffs:
+    OpenItemDiffs:
       type: object
       properties:
         namespace:
-          $ref: '#/components/schemas/NamespaceIdentifier'
-          description: ''
+          $ref: '#/components/schemas/OpenNamespaceIdentifier'
         diffs:
-          $ref: '#/components/schemas/ItemChangeSets'
-          description: ''
+          $ref: '#/components/schemas/OpenItemChangeSets'
         extInfo:
           type: string
-          description: ''
-    NamespaceSyncModel:
+          description: '扩展信息'
+    OpenNamespaceSyncModel:
       type: object
       properties:
         syncToNamespaces:
           type: array
           items:
-            $ref: '#/components/schemas/NamespaceIdentifier'
-            description: com.ctrip.framework.apollo.portal.entity.vo.NamespaceIdentifier
-          description: ''
+            $ref: '#/components/schemas/OpenNamespaceIdentifier'
+          description: 目标命名空间标识列表
         syncItems:
           type: array
           items:
-            $ref: '#/components/schemas/ItemDTO'
-            description: com.ctrip.framework.apollo.common.dto.ItemDTO
-          description: ''
-
-
-    ReleaseDTO:
-      type: object
-      properties:
-        dataChangeCreatedBy:
-          type: string
-          description: ''
-        dataChangeLastModifiedBy:
-          type: string
-          description: ''
-        dataChangeCreatedByDisplayName:
-          type: string
-          description: ''
-        dataChangeLastModifiedByDisplayName:
-          type: string
-          description: ''
-        dataChangeCreatedTime:
-          type: string
-          description: ''
-        dataChangeLastModifiedTime:
-          type: string
-          description: ''
-        id:
-          type: integer
-          description: ''
-          format: int64
-        releaseKey:
-          type: string
-          description: ''
-        name:
-          type: string
-          description: ''
-        appId:
-          type: string
-          description: ''
-        clusterName:
-          type: string
-          description: ''
-        namespaceName:
-          type: string
-          description: ''
-        configurations:
-          type: string
-          description: ''
-        comment:
-          type: string
-          description: ''
-        isAbandoned:
-          type: boolean
-          description: ''
+            $ref: '#/components/schemas/OpenItemDTO'
+          description: 需要同步的配置项列表
     KVEntity:
       type: object
       properties:
         key:
           type: string
-          description: ''
+          description: 键
         value:
           type: string
-          description: ''
-    ListReleaseBO:
+          description: 值
+    OpenReleaseBO:
       type: object
       properties:
         baseInfo:
-          $ref: '#/components/schemas/ReleaseDTO'
-          description: ''
+          $ref: '#/components/schemas/OpenReleaseDTO'
         items:
           type: array
           items:
             $ref: '#/components/schemas/KVEntity'
-            description: com.ctrip.framework.apollo.portal.entity.bo.KVEntity
-          description: ''
-    EntityPairKVEntity:
-      type: object
-      properties:
-        firstEntity:
-          $ref: '#/components/schemas/KVEntity'
-          description: ''
-        secondEntity:
-          $ref: '#/components/schemas/KVEntity'
-          description: ''
-    Change:
-      type: object
-      properties:
-        type:
-          type: string
-          description: ''
-          enum:
-            - ADDED
-            - MODIFIED
-            - DELETED
-        entity:
-          $ref: '#/components/schemas/EntityPairKVEntity'
-          description: ''
-
     OpenInstanceConfigDTO:
       type: object
       properties:
         release:
           $ref: '#/components/schemas/OpenReleaseDTO'
-          description: ''
         releaseDeliveryTime:
           type: string
-          description: ''
+          description: 配置下发时间（ISO 8601）
+          example: "2025-09-29T12:34:56Z"
         dataChangeLastModifiedTime:
           type: string
-          description: ''
-    OpenInstanceDTO: &ref_3
+          description: 最后修改时间（ISO 8601）
+          example: "2025-09-29T12:34:56Z"
+    OpenInstanceDTO:
       type: object
       properties:
         id:
           type: integer
-          description: ''
+          description: 实例ID
           format: int64
         appId:
           type: string
-          description: ''
+          description: 实例所属应用ID
         clusterName:
           type: string
-          description: ''
+          description: 实例所属集群名称
         dataCenter:
           type: string
-          description: ''
+          description: 数据中心/机房标识
         ip:
           type: string
-          description: ''
+          description: 实例IP地址
         configs:
           type: array
           items:
             $ref: '#/components/schemas/OpenInstanceConfigDTO'
-            description: com.ctrip.framework.apollo.openapi.dto.OpenInstanceConfigDTO
-          description: ''
+          description: 实例当前生效的配置列表
         dataChangeCreatedTime:
           type: string
-          description: ''
-
-
-
+          description: 数据创建时间（ISO 8601）
+          example: "2025-09-29T12:34:56Z"
     OpenOrganizationDto:
       type: object
       properties:
         orgId:
           type: string
-          description: ''
+          description: 组织ID
         orgName:
           type: string
-          description: ''
+          description: 组织名称
+    ExceptionResponse:
+      type: object
+      additionalProperties: true   # 对应 server 中 GlobalExceptionHandler返回Map<String,Object>
+      description: >
+        错误响应对象，表示为 Map<String,Object>。
+        字段包括：
+        - status: HTTP 状态码 (integer)
+        - message: 错误信息 (string)
+        - timestamp: 出错时间戳 (string)
+        - exception: 异常类名或标识 (string)
+      example:
+        status: 404
+        message: "Resource not found"
+        timestamp: "2025-09-29T12:34:56Z"
+        exception: "NotFoundException"
+    SuccessEmptyResponse: # 对应 ResponseEntity<Void> 是一个通用的空返回数据模型，不带任何信息，用于成功时的返回
+      type: object
+      properties: {}
+    StringToStringBoolMap: # Map<String, Map<String, Boolean>>
+      type: object
+      additionalProperties:
+        type: object
+        additionalProperties:
+          type: boolean
+      example:
+        projectA:
+          featureX: true
+          featureY: false
+        projectB:
+          darkMode: true
 
 
 servers: []
diff --git a/generate.sh b/generate.sh
index 0aa93630..7848d03f 100755
--- a/generate.sh
+++ b/generate.sh
@@ -47,6 +47,14 @@ openapi-generator generate \
 echo "📦 Adding Maven Wrapper to Spring Boot 2 project..."
 cd "$SPRING_BOOT2_DIR"
 mvn -N io.takari:maven:wrapper -Dmaven=3.8.6
+
+# this is for removing illegal symbols generated by a generator.
+echo "Cleaning files (trailing spaces, CRLF, EOF newlines)..."
+find . -type d \( -name .git -o -name .idea -o -name .mvn -o -name target -o -name build -o -name node_modules \) -prune -o \
+  -type f \( -name "*.java" -o -name "*.xml" -o -name "*.properties" -o -name "*.md" -o -name "*.yml" -o -name "*.yaml" -o -name "*.sh" -o -name ".editorconfig" -o -name ".gitignore" -o -name "mvnw" \) -print0 \
+| xargs -0 perl -i -0777 -pe 's/[ \t]+(?=\r?$)//mg; s/\r//g; s/\s*\z/\n/s'
+echo "Cleaning files (trailing spaces, CRLF, EOF newlines)... Done!"
+
 cd ..
 
 echo "💡 Spring Boot 2 project ready! To start the server, run:"