fix: Swagger resolveSchema drops every direct-$ref property (60 of 225 endpoints)

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>
                 ) : (

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({});
+  });
+});

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;