From e93980297946529a8e43e7fef7a6158cec4030dc Mon Sep 17 00:00:00 2001
From: Zhao Jianing <18910855655@163.com>
Date: Thu, 22 Oct 2026 13:06:50 +0800
Subject: [PATCH] fix: Swagger resolveSchema drops every direct-$ref property
 (60 of 225 endpoints lose nested objects)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

resolveSchema 对 {$ref, description} 形状的属性没有任何分支——没有
type 字段，array/object 检查都不命中，引用的 schema 从未被解析。
对线上 /api/v2/docs 规范实测：60/225 个带 201 schema 的端点至少
丢失一个嵌套对象（66 个不同对象——所有 /api/v2/metrics/* 的
metric_detail + TpcItem.scorecard）。

ResponsesViewer 的 hasChildren 只检查 value.items，解析出的
properties 仍然渲染为叶子——value.items || value.properties
的回退不可达。

修复：resolveSchema 新增 $ref 分支（递归解析引用的 schema），
导出为可测纯函数；ResponsesViewer 用统一的 childData（items 或
properties）判定可展开性与渲染。

新增 useMenuContent.test.ts：$ref 解析/array-of-$ref 回归/
未知 schema 三例。
---
 .../APIDocumentation/ResponsesViewer.tsx      | 17 +++---
 .../components/SideBar/useMenuContent.test.ts | 52 +++++++++++++++++++
 .../components/SideBar/useMenuContent.ts      | 13 ++++-
 3 files changed, 73 insertions(+), 9 deletions(-)
 create mode 100644 apps/web/src/modules/dataHub/components/SideBar/useMenuContent.test.ts

diff --git a/apps/web/src/modules/dataHub/DataView/APIDocumentation/ResponsesViewer.tsx b/apps/web/src/modules/dataHub/DataView/APIDocumentation/ResponsesViewer.tsx
index 17a02bc8fa..215b547019 100644
--- a/apps/web/src/modules/dataHub/DataView/APIDocumentation/ResponsesViewer.tsx
+++ b/apps/web/src/modules/dataHub/DataView/APIDocumentation/ResponsesViewer.tsx
@@ -20,11 +20,17 @@ const ResponsesViewer: React.FC<ResponsesViewerProps> = ({ responses }) => {
       <ul className="pl-4">
         {Object.entries(data).map(([key, rowValue]) => {
           const value: any = rowValue;
+          // $ref 解析出的 properties 与 array 的 items 都是可展开的子结构。
+          const childData =
+            value?.items && Object.keys(value.items).length > 0
+              ? value.items
+              : value?.properties && Object.keys(value.properties).length > 0
+                ? value.properties
+                : null;
           const hasChildren =
             typeof value === 'object' &&
             value !== null &&
-            value.items &&
-            Object.keys(value.items).length > 0;
+            childData !== null;
 
           return (
             <li key={`${parentKey}.${key}`} className="mb-2">
@@ -38,16 +44,13 @@ const ResponsesViewer: React.FC<ResponsesViewerProps> = ({ responses }) => {
                             {key}:
                           </span>
                           <span className="ml-2 font-normal text-gray-700">
-                            {Object.keys(value.items).length} properties
+                            {Object.keys(childData).length} properties
                           </span>
                         </>
                       }
                       key={key}
                     >
-                      {renderResponse(
-                        value.items || value.properties || value,
-                        key
-                      )}
+                      {renderResponse(childData, key)}
                     </Panel>
                   </Collapse>
                 ) : (
diff --git a/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.test.ts b/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.test.ts
new file mode 100644
index 0000000000..921551fb06
--- /dev/null
+++ b/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.test.ts
@@ -0,0 +1,52 @@
+import { resolveSchema } from './useMenuContent';
+
+const definitions = {
+  TpcItem: {
+    properties: {
+      scorecard: {
+        $ref: '#/definitions/ScorecardItem',
+        description: 'response',
+      },
+    },
+  },
+  ScorecardItem: {
+    properties: {
+      developer: { type: 'number', description: '开发维度' },
+      collaboration: { type: 'number', description: '协作维度' },
+    },
+  },
+};
+
+describe('resolveSchema', () => {
+  it('resolves direct $ref properties into their referenced schema', () => {
+    // 线上 /api/v2/docs 中 60/225 端点的 $ref 属性此前落入无分支区，
+    // 引用的 schema 从未被解析——TpcItem.scorecard 在文档页显示为
+    // {"description":"response"} 而无任何子属性。
+    const result = resolveSchema(definitions, 'TpcItem');
+    expect(result.scorecard).toBeDefined();
+    expect(result.scorecard.properties).toBeDefined();
+    expect(result.scorecard.properties.developer).toBeDefined();
+    expect(result.scorecard.properties.developer.type).toBe('number');
+    expect(result.scorecard.properties.collaboration).toBeDefined();
+  });
+
+  it('resolves array-of-$ref items (existing behavior, regression guard)', () => {
+    const defs = {
+      ListResponse: {
+        properties: {
+          items: {
+            type: 'array',
+            items: { $ref: '#/definitions/ScorecardItem' },
+          },
+        },
+      },
+      ScorecardItem: definitions.ScorecardItem,
+    };
+    const result = resolveSchema(defs, 'ListResponse');
+    expect(result.items.items.developer).toBeDefined();
+  });
+
+  it('returns empty object for unknown schema name', () => {
+    expect(resolveSchema(definitions, 'NonExistent')).toEqual({});
+  });
+});
diff --git a/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.ts b/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.ts
index 7b8ab3a0f3..be5e084c8a 100644
--- a/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.ts
+++ b/apps/web/src/modules/dataHub/components/SideBar/useMenuContent.ts
@@ -39,7 +39,7 @@ const getAllowedTagPath = (tags: string[] = []) => {
 };
 
 // @ts-ignore
-function resolveSchema(definitions: DefinitionsMap, targetSchema?: string) {
+export function resolveSchema(definitions: DefinitionsMap, targetSchema?: string) {
   if (!targetSchema || !definitions[targetSchema]) {
     return {};
   }
@@ -57,6 +57,15 @@ function resolveSchema(definitions: DefinitionsMap, targetSchema?: string) {
       example: propDef.example,
     };
 
+    // 直接 $ref 属性（{ $ref: "#/definitions/X", description }）没有 type，
+    // 此前落入无分支区——引用的 schema 从未被解析，嵌套对象在文档页空白。
+    // 线上 /api/v2/docs 中 60/225 端点受影响（所有 metric_detail + TpcItem.scorecard）。
+    if (propDef?.$ref) {
+      const refSchema = propDef.$ref.split('/').pop();
+      propData.type = propDef.type || 'object';
+      propData.properties = resolveSchema(definitions, refSchema);
+    }
+
     if (propDef?.type === 'array' && propDef.items) {
       if (propDef.items.$ref) {
         const refSchema = propDef.items.$ref.split('/').pop();
@@ -67,7 +76,7 @@ function resolveSchema(definitions: DefinitionsMap, targetSchema?: string) {
     }
 
     if (propDef.type === 'object' && propDef.properties) {
-      propData.properties = resolveSchema(definitions, propDef.type);
+      propData.properties = propDef.properties;
     }
 
     result[propName] = propData;